WorkGraph watches your Claude Code and Codex sessions and compiles everything useful into a structured memory directory — .workgraph/ — that lives alongside your code.

When 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.

The problem it solves

Every 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.

WorkGraph turns those sessions into memory that compounds.

Web UI

Run 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.

Switch to Map for the full force-directed knowledge graph:

The UI has five modes:

• Overview — readable milestone timeline, default on open
• Projects — switch between tracked repos
• Map — force-directed knowledge graph (D3)
• Reusable — exported skills and reusable patterns
• Outputs — rendered markdown artifacts (journey, traps, templates, skills)

How it works

flowchart LR
    CC("🤖 Claude Code\nsessions") --> W
    CX("🤖 Codex\nsessions") --> W
    MI("📄 Manual\nimport") --> W
    W(["⬡ WorkGraph"]):::wg --> JM("📖 journey.md")
    W --> BR("⚡ agent brief")
    W --> SK("♻️ reusable skills")
    W --> EV("🔍 evals + traps")
    W --> UI("🌐 web UI")
    classDef wg fill:#1b1b30,stroke:#818cf8,color:#a5b4fc

WorkGraph 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.

Install

npm install -g agent-workgraph

Requires Node.js ≥ 20

Quick Start

Run this inside the repo you want WorkGraph to learn from:

# Install hooks for Claude Code + Codex, then start watching
workgraph install all .
workgraph start

Open the UI at http://127.0.0.1:8787 — WorkGraph backfills your recent sessions and writes compiled memory into .workgraph/.

Stop when done:

workgraph stop

If You Use Codex App

First install WorkGraph once from a terminal:

npm install -g agent-workgraph
workgraph install codex .

Then open Codex in your project and say:

Use the WorkGraph skill and start listening.

Codex will start WorkGraph for that repo and the UI will be at http://127.0.0.1:8787.

Use From Inside Your Agent

After workgraph install all ., these slash commands are available directly in Claude Code:

/workgraph                          # start or check status
/workgraph status                   # see what's compiled
/workgraph reuse graph visualization
/workgraph export Force graph visualization

If Claude is opened from your home folder, pass the project path:

/workgraph /absolute/path/to/project

In Codex:

Use the WorkGraph skill and start listening.
Use WorkGraph reuse graph visualization.
Use WorkGraph export skill Force graph visualization.

What Gets Produced

WorkGraph writes a set of structured files into your repo's .workgraph/ directory:

| File | What it contains | |---|---| | journey.md | Human-readable project story, milestone by milestone | | workgraph.md | Full summary: rules, failures, evals, open questions | | work_items.jsonl | Every captured task with outcome + learned rule | | failure_patterns.jsonl | Recurring mistakes and how they were resolved | | generated_evals.jsonl | Eval checks that emerged from session work | | repo_rules.md | Constraints the agent should always follow | | agent_instructions.md | What to do at session start | | known_traps.md | Failure patterns, formatted for agent context | | task_templates.md | Reusable task patterns from this repo | | onboarding.md | Getting-started guide generated from sessions |

Cross-repo reusable skills go to ~/.workgraph/skills/:

~/.workgraph/skills/
  force-graph-visualization.json
  force-graph-visualization.md

Reuse a Pattern in Another Repo

Export a skill from the current repo:

workgraph skill export "Force graph visualization" . --query "graph visualization UI"

Pull it into a different project:

workgraph reuse "graph visualization"

WorkGraph returns the pattern, checks, traps, and source context — without needing the original chat.

Session Sources

WorkGraph discovers sessions automatically:

| Source | Location | |---|---| | Codex app / CLI rollout JSONL | ~/.codex/sessions/ | | Codex thread metadata | ~/.codex/state_5.sqlite | | Codex archived sessions | ~/.codex/archived_sessions/ | | Claude Code JSONL | ~/.claude/projects/<encoded-path>/ | | Claude desktop summaries | ~/Library/Application Support/Claude/claude-code-sessions/ | | Manual imports | .workgraph/imports/ |

Manual import:

mkdir -p .workgraph/imports
cp session.md .workgraph/imports/
workgraph compile .

Commands

# Lifecycle
workgraph install [all|claude|codex] [repo]
workgraph start   [repo] [codex|claude|all]
workgraph stop    [repo]
workgraph status  [repo]

# Compile & watch
workgraph compile [repo] [--provider heuristic|local|ollama|claude-cli|codex-cli]
workgraph watch   [repo] [--interval <seconds>] [--once]

# Explore
workgraph ui      [repo] [--port <port>]
workgraph brief   "task description" [repo] [--json]

# Skills
workgraph skill export "Name" [repo] [--query "what to extract"]
workgraph skill list
workgraph skill search "what you want to reuse"
workgraph reuse   "what you want to reuse"

# Reset
workgraph reset   [repo] --yes-delete

Privacy

By default WorkGraph is fully local — it reads local agent logs and writes local files. Nothing is sent anywhere.

Model-backed compilation is opt-in:

# Local model via Ollama
workgraph compile . --provider ollama --model llama3.1

# Cloud-backed (requires explicit consent flag)
workgraph compile . --provider claude-cli --yes-send-logs
workgraph compile . --provider codex-cli  --yes-send-logs

--yes-send-logs is required for any provider that may transmit session data — WorkGraph refuses without it.

Status

WorkGraph 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.

Use --provider ollama when you want richer model-backed extraction without sending data to the cloud.