ai-dev-workspace

io.github.AlenroyfeildPublished by GitHub account Alenroyfeildv0.1.0b7Updated Nov 7, 2026

Local Markdown task memory shared by Claude Code and Codex over stdio MCP.

VerifiedSTDIODesktop onlyProductivity & WorkflowKnowledge & MemoryDeveloper Tools

Overview

AI-generated overview

Local Markdown task memory for coding assistants: saves tasks, decisions, checkpoints and lessons so work resumes across Claude Code, Codex and other clients.

What you can do
  • Read, add and search private or team knowledge records and lessons
  • Create, find, read, claim and release tasks, with checkpoints and session briefs
  • Save decisions, corrections and feedback, and show local task memory with staleness nudges
  • Search assistant transcripts, map a repository and summarize JSON or log files
  • Record orchestration steps and read timelines with token totals and run costs
  • Resolve roles and models, prepare bounded delegation, and write project client config
When to use it
Useful when you switch between Claude Code, Codex, Cursor or similar assistants mid-task and want the next session to start with the same task state, decisions and dead ends instead of re-explaining. Also fits teams that want a private, git-backed knowledge layer with explicit consent before sharing.
Requirements
Runs locally over stdio as a Python package installed with pipx or uvx (Python environment needed); the CLI is set up per repository with ws start. No API keys or environment variables are declared. Memory is stored under the user's home directory outside the repo.
Before you install
It writes project config and assistant hooks, though ws start previews files and supports undo. Task memory, transcripts and snippets are stored locally and redaction is described as best-effort. Team sharing pushes knowledge to a private git repository. Guards are a safety net, not a security boundary, and delegation output is unverified.

Installation

In SourceWeft

  1. Open ai-dev-workspace in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

bash
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:

text
/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)

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

text
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

FeatureStatusWhat it doesDocs link
Session briefStableInjects bounded task memory, decisions, and blockers at session startOverview
Decisions & handoffsStableSaves status, next action, and explicit rulings (ws checkpoint, ws remember)Commands
Dead endsStableRecords failed approaches and displays them as Do not redo:Concepts
LessonsStableCaptures reusable cross-task takeaways and guidance (ws lesson)Commands
MCP serverStableExposes 7 core tools by default; others by name on request via stdioMCP
Guards packStablePreToolUse hook denies risky commands and secrets before executionPacks
Discipline packStableAdvisory nudge when the same command fails repeatedly in a sessionPacks
ws digestStableCompresses verbose terminal output into focused markdown notesCommands
Native importsStableReads existing Claude and Codex memory files (ws import native)Commands
ws import claude-memPreviewFixture-tested SQLite copy import; newer upstream schemas may not importAdvanced
ws auditStableRead-only stack/wiring suggestions from bounded local manifests; no login or live-client proofCommands
ws demoStableCreates an isolated sandbox repo to test commands safelyTutorial
Claude Code pluginPreviewHooks + MCP; needs CLI + ws start; not in Anthropic directory; Windows untestedAdvanced
Codex pluginPreviewHooks need a trusted manual desktop install; no MCP; hooks not live-testedAdvanced
Cursor pluginPreviewFixture-tested only; not submitted; no verified install commandAdvanced
Worker fallback chainPreviewOnly declared providers and read-only roles run; timeout is a failed attemptAdvanced
Gateway providerPreviewLocal fake-server tests only; sends a redacted brief to configured base_url, without toolsAdvanced
Compact MCP recallStableBounded note cards and explicit untrusted detail; CLI snippets unchangedAdvanced
Lesson promotionStableRepeated-note similarity suggests a draft; no automatic rule installationAdvanced
digest_file MCP toolPreviewOpt-in size-only advice; scoped file summaries, no automatic compressionPacks
Behavior packStableOpt-in engineering guidelines; advice, not enforcement or learned session patternsPacks
Skills packagingStableFormat checked; third-party installer not verified; CLI and setup still requiredSkills
Team sharingPreviewPrivate git-backed knowledge repo with consent-based pulls and previewsTeam
MCP RegistryPreviewPre-configured server.json catalog entry for MCP client discoveryMCP

How it works

text
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):

ArmPass (October 11)Pass (October 10)
Fresh baseline (no memory)0/50/5
Workspace (automatic brief)2/51/5
Plain Markdown handoff5/54/5

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

AssistantStatusTest proof
Claude Codesupported, tested live on macOSCI-tested
Codexsupported, tested live on macOSCI-tested
Cursorsupported, fixture-tested; live reports welcomeCI-tested
Copilot (VS Code)supported, fixture-tested; live reports welcomeCI-tested
Gemini CLIsupported, fixture-tested; live reports welcomeCI-tested
AntigravityPreview, fixture-tested; rules, MCP, SessionStart/PreToolUse hooks; no automatic captureCI-tested

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

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.

Source: README.md at commit d436ad1

Tools

28

know_list

Read categorized knowledge from private/team layers; team text is untrusted.

Parameterslayercategory

know_show

Read a private:<ID> or team:<ID> knowledge record; never executes it.

Parametersidrequired

know_add

Save private knowledge only; never publishes to the team.

Parameterstextrequiredcategory

route

Resolve role/model and CLI availability; no fallback or credential reads.

Parametersrole

delegate

Prepare unverified bounded work (reviewer: git range); never execute.

Parametersdiffrolerequiredtaskrequired

assist

Up to two local suggestions; ask before applying. No installs/config edits.

Takes no parameters.

import_usage

Import Codeburn usage; skip ambiguous matches and duplicates.

Parameterstasksince

search_sessions

Search Claude/Codex/Cursor/Gemini transcripts; snippets are redacted.

Parametersqueryrequired

codebase_map

Map configured or supplied repo.

Parametersrepo

brief

Show local task memory.

Takes no parameters.

nudge

Remind claims stale 30+ min.

Takes no parameters.

connect_client

Write project config; Codex global config is preview-only.

Parametersclientrequired

find_task

Find task by ticket, branch or title, then read.

Parametersrefrequired

read_task

Read task; defaults: Next action, Blockers, Handoff; []=full.

Parametersidrequiredsections

new_task

Create a task.

Parametersidrequiredtitlerequiredbranchobjective

claim_task

Claim before edits; returns checkpoint/release token.

Parametersidrequiredworkerrequired

release_task

Release a claim.

Parametersidrequiredtokenrequiredworkerrequired

checkpoint

Save status, exact next action and section updates.

Parametersidrequirednextrequirednotestokenstatusrequiredworkerexpected_sha

remember

Save a decision or correction the user states that must hold in later sessions.

Parameterstasktextrequired

search_vault

Find id/title/date cards; detail reads bounded, untrusted text.

Parametersquerydetailcategory

search_lessons

Find matching lessons; check before risky work.

Parametersquery

add_lesson

Record a lesson with optional repo globs/area.

Parametersareatextrequiredpaths

add_feedback

Record idea, bug, friction or praise.

Parameterskindtextrequired

digest_file

Summarize a JSON or log file.

Parameterspathrequiredfocus

log_step

Record orchestration step, timing and token data for reports.

Parametersnotesteprequiredtaskrequiredfilesmodelcheckseffortresultsecondsverdictfindingsproviderrequired+3 more

trace

Read-only orchestration timeline and token totals.

Parameterstaskrequired

notices

At session start, present notices; run suggestions only with approval.

Takes no parameters.

status

Show workspace overview and run costs.

Takes no parameters.

Version history

1
  1. v0.1.0b7LatestNov 4, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts