ai-dev-workspace

AI Dev Workspace

Your assistant remembers work between sessions in Markdown you own. Shared, durable task memory for developers who switch between Claude Code, Codex, and other assistants.

[PyPI version] [CI] [Python 3.9+] [License: MIT]

[Switch from Claude Code to Codex: the saved decision follows the task (animation)]

Quick start

Try offline before connecting a repo: ws demo · 5-minute tutorial · Claude Code + Codex guide · remove it

pipx install ai-dev-workspace --pip-args='--pre'  # beta; omit --pip-args after a stable releasecd ~/code/myapp && ws start

No pipx? brew install pipx, or python3 -m venv ~/.ws && ~/.ws/bin/pip install --pre ai-dev-workspace; put its bin directory on PATH before ws start.

Prefer a Claude Code plugin? Preview. Not yet listed in Anthropic's official plugin directory; install from our GitHub marketplace:

/plugin marketplace add Alenroyfeild/ai-dev-workspace/plugin install ai-dev-workspace@ai-dev-workspace

Live-checked on beta.5 (2026-10-22). See the plugin preview.

ws start previews every file and writes nothing until you confirm. Generated assistant hooks and configs stay local (.git/info/exclude), task memory lives outside the repo in ~/.ai-dev-workspace/<repo-name>, and ws start --undo cleanly removes repo wiring.

Watch (videos for 0.1.0b6)

• Watch the 2-minute explainer
• Under the hood: real commands, real output
• Feature shorts: Switch assistants · Resume the next step · Dead ends · Skills · Team workspace (Preview) · Guards · Assistants · Install as a plugin (Preview)
• Earlier editions: 0.1.0b5

Use cases

• Switch Claude Code ↔ Codex mid-task: Start in Claude Code, save a checkpoint, and continue in Codex with the exact same brief and task memory (guide).
• Resume tomorrow without re-explaining: Inject active tasks, recent decisions, and blockers directly into context at session start (tutorial).
• Stop retrying failed approaches: Dead ends appear under Do not redo: in every fresh session brief (guide).
• Keep verified corrections: Record decisions or constraints with ws remember so fresh sessions follow earlier rulings (commands).
• Block risky commands and leaks: Opt-in guards pack denies dangerous shell operations and secrets in commands or written files (packs).
• Share domain notes with a team (preview): Share approved knowledge via private git repository with consent-based previews (team).

Example

Session 1 — You: “Empty email returns missing_email; leave signup unchanged.”Assistant: “I’ll trace login and keep the decision with this task.”You: “Save a checkpoint and stop here.”
Session 2 — You: “Continue the login fix.”Assistant: “The saved note says return missing_email and leave signup unchanged.”You: “Yes, continue.”

Features

How it works

Claude Code / Codex / Cursor / Copilot / Gemini / Antigravity        │ (session startup & capture hooks)        ▼~/.ai-dev-workspace/<repo-name>/           (private, outside repo)  ├── workspace.json                       (settings, active task, packs)  └── vault/      ├── Tasks/<id>.md                    (status, next action, decisions, blockers)      └── Learnings.md                     (reusable cross-task lessons & dead ends)        ▲        │ (MCP stdio connection: 7 core tools by default; others by name)  Local Assistant (MCP client)

Memory storage makes no background model calls. ws delegate --run starts only declared assistant CLIs or sends a redacted brief to an explicitly configured gateway; output is unverified. Task memory is plain Markdown you own.

Results

Measured in bench/README.md across independent paired investigations (Codex gpt-6-luna, n=5 per cohort):

The latest controlled runs show the plain Markdown handoff beating the workspace (5/5 and 4/5 against 2/5 and 1/5), with the automatic-capture release gate still unmet. The win for the workspace is structure, cross-assistant handoff, and avoiding manual file management. Details and earlier runs: bench/README.md and docs/MEASUREMENTS.md.

Compared with

• Built-in memory files (CLAUDE.md, AGENTS.md): Plain instructions per assistant; ai-dev-workspace adds cross-assistant handoffs, active task state, and Do not redo: constraints.
• A plain HANDOFF.md: Works well for manual notes (and beat automatic workspace capture in latest benchmark cohorts: 5/5 vs 2/5); ai-dev-workspace adds cross-assistant automation, structured brief injection, and staleness warnings.
• claude-mem: Captures tool use through hooks and compresses it with AI into SQLite + vector search (upstream docs), providing automatic memory capture without explicit commands; ai-dev-workspace keeps explicit Markdown you own, makes no background model calls for memory (explicit delegation can call declared CLIs or a configured gateway), and focuses on durable handoffs with next steps and dead ends (guide).

Compatibility

Testers on Cursor, Copilot (VS Code), Gemini CLI, or Antigravity: please share problems through Something broke.

Known limits

• Client coverage: Claude Code and Codex are live-tested on macOS; Linux and Windows are CI-tested only. Cursor, Copilot (VS Code), Gemini CLI, and Antigravity are fixture-tested.
• Capture is best-effort: Explicit CLI commands (ws remember, ws checkpoint) are deterministic; automatic transcript cue-word capture is best-effort.
• Guards are a safety net: Pattern matching blocks common risky commands and secrets in commands or written files, but is not an unbypassable security boundary.
• Team sharing: Multi-user flow tested on one Mac over a local HTTPS Git server: three separate profiles, sharing in both directions, generated Claude Code and Codex hook output. A hosted GitHub check and live assistant sessions are pending. (Roadmap)

Privacy & safety

• Private by default: Memory is stored outside checkout paths in ~/.ai-dev-workspace/<repo-name>. Team sharing requires an explicit private repo (ws team init) with manual confirmation.
• Redaction is best-effort: ws masks known API keys, tokens, and private spans (<private>...</private>), but regex redaction is best-effort and does not replace operational secret hygiene.
• Guards are a safety net: The guards PreToolUse hook blocks known risky shell patterns and secrets in commands or written files, but it is a safety net, not an unbypassable security boundary.

Coming next

• Common Agent Plugins manifest (PLG3): parked and unavailable until Codex can load the root manifest without losing plugin hooks.
• Codex plugin MCP through roots (PLG5): parked and unavailable for Codex; codex-cli 0.155.1 offers no roots and cannot expand plugin MCP paths, so use ws start for MCP. Clients that offer roots get the beta.7 Preview.

Documentation

• Start: 5-minute tutorial · Setup guide · Demo walkthrough · Cross-client guide
• Use: CLI commands · Packs catalog · Skills distribution · MCP server · Advanced usage
• Guides: Keep decisions without background AI · Stop retrying dead ends
• Team: Team use · Team workspace setup
• Reference: Overview · Architecture · Benchmark measurements · Client verification · Windows support · Roadmap

Status & contributing

ai-dev-workspace is in public beta (v0.1.0-beta.6 on PyPI). Planned improvements are tracked in the Roadmap. Bug reports and feedback are welcome through Something broke.

Released under the MIT License.