{"_id":"agent-workgraph","name":"agent-workgraph","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"agent-workgraph","version":"0.1.0","description":"Turn AI coding sessions into reusable engineering memory, evals, and agent briefs.","type":"module","homepage":"https://github.com/ranausmanai/agent-workgraph#readme","bugs":{"url":"https://github.com/ranausmanai/agent-workgraph/issues"},"repository":{"type":"git","url":"git+https://github.com/ranausmanai/agent-workgraph.git"},"keywords":["ai","agents","codex","claude","developer-tools","evals","memory"],"bin":{"workgraph":"bin/workgraph.js"},"scripts":{"test":"node --test","pack:check":"npm pack --dry-run","prepublishOnly":"npm test && npm run pack:check"},"engines":{"node":">=20"},"license":"MIT","dependencies":{"d3":"^7.9.0","marked":"^12.0.2"},"gitHead":"c187aae235f837dc440879d73a1ff7aa90c9c4e3","_id":"agent-workgraph@0.1.0","_nodeVersion":"25.8.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-JMqRmV1/88Jil4v4EcSxP5yzfEimUNfpndHc5PdvdQEk775ENy7cxS1cth4FHxifU+/8y+8uJVa5WuLu4vMn1g==","shasum":"813bc8d4b26d1238fd67f0c0c152533686b4f388","tarball":"https://registry.npmjs.org/agent-workgraph/-/agent-workgraph-0.1.0.tgz","fileCount":32,"unpackedSize":2230490,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCxb8F7akj5+69xToM4eJILycxV3AENAann7f2p/iYFewIhAKGG4hhTscaOeDHhOloKWqogVnBlLG5TYN69OX6tOOip"}]},"_npmUser":{"name":"ranausman","email":"usmanashrafrana@gmail.com"},"directories":{},"maintainers":[{"name":"ranausman","email":"usmanashrafrana@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-workgraph_0.1.0_1777977292134_0.1028148069184267"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-05T10:34:52.037Z","0.1.0":"2026-05-05T10:34:52.317Z","modified":"2026-05-05T10:34:52.532Z"},"maintainers":[{"name":"ranausman","email":"usmanashrafrana@gmail.com"}],"description":"Turn AI coding sessions into reusable engineering memory, evals, and agent briefs.","homepage":"https://github.com/ranausmanai/agent-workgraph#readme","keywords":["ai","agents","codex","claude","developer-tools","evals","memory"],"repository":{"type":"git","url":"git+https://github.com/ranausmanai/agent-workgraph.git"},"bugs":{"url":"https://github.com/ranausmanai/agent-workgraph/issues"},"license":"MIT","readme":"<div align=\"center\">\n\n<img src=\"docs/banner.svg\" alt=\"WorkGraph — Turn AI coding sessions into reusable engineering memory\" width=\"100%\">\n\n<br>\n\n[![npm](https://img.shields.io/npm/v/agent-workgraph?style=flat-square&color=818cf8&label=npm)](https://npmjs.com/package/agent-workgraph)\n[![node](https://img.shields.io/node/v/agent-workgraph?style=flat-square&color=34d399)](https://nodejs.org)\n[![license](https://img.shields.io/npm/l/agent-workgraph?style=flat-square&color=38bdf8)](LICENSE)\n[![local-first](https://img.shields.io/badge/local--first-no%20cloud-60a5fa?style=flat-square)](#privacy)\n\n</div>\n\n<br>\n\n**WorkGraph** watches your Claude Code and Codex sessions and compiles everything useful into a structured memory directory — `.workgraph/` — that lives alongside your code.\n\nWhen a new session starts, WorkGraph gives the agent a short **brief**: what was built, what broke, what to watch out for. No dumping old chat history. No context waste.\n\n---\n\n## The problem it solves\n\nEvery time you start a new AI coding session, the agent starts from zero. It doesn't know what was tried last time, what rules emerged, what files were touched, or what traps to avoid. You end up re-explaining context, watching the agent repeat known mistakes.\n\nWorkGraph turns those sessions into memory that compounds.\n\n---\n\n## Web UI\n\nRun `workgraph ui .` and open `http://127.0.0.1:8787` to see your project's full journey — every milestone, what was built, confidence levels, known traps, and files touched.\n\n![WorkGraph Overview — milestone timeline](docs/screenshot-overview.png)\n\nSwitch to **Map** for the full force-directed knowledge graph:\n\n![WorkGraph Map — knowledge graph](docs/screenshot-map.png)\n\nThe UI has five modes:\n- **Overview** — readable milestone timeline, default on open\n- **Projects** — switch between tracked repos\n- **Map** — force-directed knowledge graph (D3)\n- **Reusable** — exported skills and reusable patterns\n- **Outputs** — rendered markdown artifacts (journey, traps, templates, skills)\n\n---\n\n## How it works\n\n```mermaid\nflowchart LR\n    CC(\"🤖 Claude Code\\nsessions\") --> W\n    CX(\"🤖 Codex\\nsessions\") --> W\n    MI(\"📄 Manual\\nimport\") --> W\n    W([\"⬡ WorkGraph\"]):::wg --> JM(\"📖 journey.md\")\n    W --> BR(\"⚡ agent brief\")\n    W --> SK(\"♻️ reusable skills\")\n    W --> EV(\"🔍 evals + traps\")\n    W --> UI(\"🌐 web UI\")\n    classDef wg fill:#1b1b30,stroke:#818cf8,color:#a5b4fc\n```\n\nWorkGraph reads local session logs, runs a compiler (heuristic by default, model-backed optionally), and writes structured artifacts into `.workgraph/`. Nothing leaves your machine unless you explicitly opt in.\n\n---\n\n## Install\n\n```bash\nnpm install -g agent-workgraph\n```\n\n> Requires Node.js ≥ 20\n\n---\n\n## Quick Start\n\nRun this inside the repo you want WorkGraph to learn from:\n\n```bash\n# Install hooks for Claude Code + Codex, then start watching\nworkgraph install all .\nworkgraph start\n```\n\nOpen the UI at `http://127.0.0.1:8787` — WorkGraph backfills your recent sessions and writes compiled memory into `.workgraph/`.\n\nStop when done:\n\n```bash\nworkgraph stop\n```\n\n---\n\n## If You Use Codex App\n\nFirst install WorkGraph once from a terminal:\n\n```bash\nnpm install -g agent-workgraph\nworkgraph install codex .\n```\n\nThen open Codex in your project and say:\n\n```text\nUse the WorkGraph skill and start listening.\n```\n\nCodex will start WorkGraph for that repo and the UI will be at `http://127.0.0.1:8787`.\n\n---\n\n## Use From Inside Your Agent\n\nAfter `workgraph install all .`, these slash commands are available directly in Claude Code:\n\n```\n/workgraph                          # start or check status\n/workgraph status                   # see what's compiled\n/workgraph reuse graph visualization\n/workgraph export Force graph visualization\n```\n\nIf Claude is opened from your home folder, pass the project path:\n\n```\n/workgraph /absolute/path/to/project\n```\n\n**In Codex:**\n\n```\nUse the WorkGraph skill and start listening.\nUse WorkGraph reuse graph visualization.\nUse WorkGraph export skill Force graph visualization.\n```\n\n---\n\n## What Gets Produced\n\nWorkGraph writes a set of structured files into your repo's `.workgraph/` directory:\n\n| File | What it contains |\n|---|---|\n| `journey.md` | Human-readable project story, milestone by milestone |\n| `workgraph.md` | Full summary: rules, failures, evals, open questions |\n| `work_items.jsonl` | Every captured task with outcome + learned rule |\n| `failure_patterns.jsonl` | Recurring mistakes and how they were resolved |\n| `generated_evals.jsonl` | Eval checks that emerged from session work |\n| `repo_rules.md` | Constraints the agent should always follow |\n| `agent_instructions.md` | What to do at session start |\n| `known_traps.md` | Failure patterns, formatted for agent context |\n| `task_templates.md` | Reusable task patterns from this repo |\n| `onboarding.md` | Getting-started guide generated from sessions |\n\nCross-repo reusable skills go to `~/.workgraph/skills/`:\n\n```\n~/.workgraph/skills/\n  force-graph-visualization.json\n  force-graph-visualization.md\n```\n\n---\n\n## Reuse a Pattern in Another Repo\n\nExport a skill from the current repo:\n\n```bash\nworkgraph skill export \"Force graph visualization\" . --query \"graph visualization UI\"\n```\n\nPull it into a different project:\n\n```bash\nworkgraph reuse \"graph visualization\"\n```\n\nWorkGraph returns the pattern, checks, traps, and source context — without needing the original chat.\n\n---\n\n## Session Sources\n\nWorkGraph discovers sessions automatically:\n\n| Source | Location |\n|---|---|\n| Codex app / CLI rollout JSONL | `~/.codex/sessions/` |\n| Codex thread metadata | `~/.codex/state_5.sqlite` |\n| Codex archived sessions | `~/.codex/archived_sessions/` |\n| Claude Code JSONL | `~/.claude/projects/<encoded-path>/` |\n| Claude desktop summaries | `~/Library/Application Support/Claude/claude-code-sessions/` |\n| Manual imports | `.workgraph/imports/` |\n\n**Manual import:**\n\n```bash\nmkdir -p .workgraph/imports\ncp session.md .workgraph/imports/\nworkgraph compile .\n```\n\n---\n\n## Commands\n\n```bash\n# Lifecycle\nworkgraph install [all|claude|codex] [repo]\nworkgraph start   [repo] [codex|claude|all]\nworkgraph stop    [repo]\nworkgraph status  [repo]\n\n# Compile & watch\nworkgraph compile [repo] [--provider heuristic|local|ollama|claude-cli|codex-cli]\nworkgraph watch   [repo] [--interval <seconds>] [--once]\n\n# Explore\nworkgraph ui      [repo] [--port <port>]\nworkgraph brief   \"task description\" [repo] [--json]\n\n# Skills\nworkgraph skill export \"Name\" [repo] [--query \"what to extract\"]\nworkgraph skill list\nworkgraph skill search \"what you want to reuse\"\nworkgraph reuse   \"what you want to reuse\"\n\n# Reset\nworkgraph reset   [repo] --yes-delete\n```\n\n---\n\n## Privacy\n\nBy default WorkGraph is fully local — it reads local agent logs and writes local files. Nothing is sent anywhere.\n\nModel-backed compilation is opt-in:\n\n```bash\n# Local model via Ollama\nworkgraph compile . --provider ollama --model llama3.1\n\n# Cloud-backed (requires explicit consent flag)\nworkgraph compile . --provider claude-cli --yes-send-logs\nworkgraph compile . --provider codex-cli  --yes-send-logs\n```\n\n`--yes-send-logs` is required for any provider that may transmit session data — WorkGraph refuses without it.\n\n---\n\n## Status\n\nWorkGraph is early. The local compiler is intentionally conservative and inspectable. The output in `.workgraph/` is plain text — open any file in an editor to see exactly what was captured.\n\nUse `--provider ollama` when you want richer model-backed extraction without sending data to the cloud.\n\n---\n\n<div align=\"center\">\n  <sub>MIT License · Built for Claude Code + Codex · No cloud required</sub>\n</div>\n","readmeFilename":"README.md","_rev":"1-24c28d5622cd4adc763c5dc6b9fce4ab"}