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.

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 release
cd ~/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.