Skip to main content

Agent Shared Workspace

Tests Python 3.9+ Zero Dependencies License: MIT

中文 | English

A dependency-free shared memory hub for multiple coding agents: plain-text Markdown SSOT + concurrency-safe CLI + Git versioning.


Why This Exists

If you run Codex, Claude Code, DeepSeek Harness, Antigravity, or other coding agents on the same codebase, each agent keeps its own isolated memory:

  • Three agents hit the exact same bug three times.
  • Yesterday's root-cause analysis disappears in today's session.
  • Passing current project status between agents turns into repetitive copy-pasting.
  • Vector-DB memory feels like a black box: hard to inspect, hard to edit, and easy to pollute silently.

This tool takes a simpler route: shared memory lives in plain Markdown files inside a local workspace, every agent reads/writes through one stdlib-only CLI guarded by a cross-process file lock, and Git handles history and rollback.

Architecture

flowchart LR
    subgraph Agents["Multiple Coding Agents (Thin Entry Pointers / Skill)"]
        A1["Codex\n~/.codex/AGENTS.md"]
        A2["Claude Code\n~/.claude/CLAUDE.md"]
        A3["DeepSeek Harness\n~/.dsh/AGENTS.md"]
        A4["Antigravity\n.agents/skills/"]
    end

    subgraph CLI["Unified Memory CLI (Python Stdlib Only)"]
        TOOL["workspace_tool.py\ninit · exp · project · handoff · guard · commit"]
        LOCK[".workspace.lock\nmsvcrt / fcntl exclusive lock"]
        TOOL --- LOCK
    end

    subgraph SSOT["Plain-Text Single Source of Truth + Git"]
        M1["AGENTS.md / NEW_PROJECT_SOP.md"]
        M2["WORKSPACE.md"]
        M3["EXPERIENCES.md"]
        M4["Project_XXX/docs/当前状态与交接.md"]
        GIT[("Local Git\nAuditable · Reversible")]
    end

    A1 & A2 & A3 & A4 --> TOOL
    TOOL --> M1 & M2 & M3 & M4
    M1 & M2 & M3 & M4 --> GIT

Real CLI Output

Real CLI Demo

One-Line Install (4 Distribution Channels)

1. Agent Skill (skills.sh / Codex / Claude Code / Antigravity / Cursor)

npx skills add MAHONGHAO1/agent-shared-workspace

Ships with a self-contained stdlib scripts/workspace_tool.py inside the skill folder.

2. Claude Code Plugin (Skill + MCP Server)

/plugin marketplace add MAHONGHAO1/agent-shared-workspace
/plugin install agent-shared-workspace

3. MCP Server (Zero Dependencies — Cursor / Claude Desktop / Antigravity)

{
  "mcpServers": {
    "agent-shared-workspace": {
      "command": "python",
      "args": ["-m", "agent_shared_workspace.mcp_server"],
      "env": {
        "PYTHONPATH": "/path/to/agent-shared-workspace/src",
        "AGENT_WORKSPACE_ROOT": "/path/to/your-workspace"
      }
    }
  }
}

Or install locally via pip install . to expose agent-workspace (CLI) and agent-workspace-mcp (MCP stdio server).

4. DeepSeek Harness Plugin Bundle

Ready-to-publish DSH bundle lives in integrations/deepseek-harness/ (dsh-agent-shared-workspace, mounts the skill via @deepseek-ai/dsh-skill-filesystem).

Quick Start

Zero third-party packages required (Python 3.9+ stdlib only):

# 1. Point to your workspace directory (defaults to cwd if unset)
export AGENT_WORKSPACE_ROOT=~/agent-workspace
# Windows PowerShell: $env:AGENT_WORKSPACE_ROOT="D:\agent-workspace"

# 2. Initialize skeleton files, workspace.config.json, .gitignore, and Git
python src/workspace_tool.py init --lang en

# 3. Create and register a project by SOP
python src/workspace_tool.py project new "ApiGateway" --owner codex

# 4. Record a tagged pitfall/experience
python src/workspace_tool.py exp add \
  --title "Non-root container fails with EACCES on bind mount" \
  --tag "docker,linux" \
  --phenomenon "Container process gets Permission denied writing to mounted volume" \
  --cause "Host directory is owned by root while container runs as uid 10001" \
  --solution "Set user: in compose or chown in entrypoint" \
  --criteria "Container successfully writes a 1 KB test file" \
  --agent "claude-code"

# 5. Search by keyword and/or tag
python src/workspace_tool.py exp search --tag docker
python src/workspace_tool.py exp search "EACCES" --tag linux
python src/workspace_tool.py exp get EXP-001

# 6. Record a structured handoff (syncs handoff doc, project README, and board)
python src/workspace_tool.py handoff 001 --agent "codex" \
  --status "Rate limiter verified" \
  --done "Implemented token bucket and 12 unit tests" \
  --evidence "tests/test_ratelimit.py 12/12" \
  --todo "Canary rollout"

# 7. Check for uncommitted changes and commit
python src/workspace_tool.py guard
python src/workspace_tool.py commit -m "docs: initialize workspace and log EXP-001"

Commands

Command Purpose
init [--lang zh|en] [--no-git] Idempotently scaffold docs, workspace.config.json, .gitignore, and Git
status [--guard] Show active projects and Git status; --guard exits with code 1 if dirty
guard Lightweight dirty-tree check (exit 0 when clean, exit 1 when dirty)
exp search [query] [--tag t] [--list-tags] Search experiences by keyword/tag or list all tags with counts
exp get EXP-001 Inspect index metadata and full entry body (or sink path)
exp add --title ... [--tag a,b] [--sink 001] Append a new experience with auto-incremented ID and index update
exp update EXP-001 --note ... Append new evidence to an existing experience instead of duplicating
project list List all Project_XXX_* directories and highest ID
project new <name> --owner <agent> Create a project directory, README, handoff file, and register it
project update <id> --status ... Sync status to both project README and workspace board
handoff <id> --agent ... --status ... --done ... Append a handoff record and atomically update README and board
commit -m <message> Stage and commit workspace changes (automatically excludes .workspace.lock)

Built-in Safeguards

  • Cross-process Reentrant File Lock: All write commands acquire .workspace.lock using msvcrt.locking on Windows and fcntl.flock on Linux/macOS. Concurrent agents serialize cleanly with zero ID collisions or torn Markdown. Timeout defaults to 10s (AGENT_WORKSPACE_LOCK_TIMEOUT to override).
  • Dirty-Tree Guard: guard and status --guard return exit code 1 whenever uncommitted edits remain, suitable for shell hooks or end-of-session checks.
  • Configurable Filenames: init --lang en writes WORKSPACE.md / EXPERIENCES.md / NEW_PROJECT_SOP.md and saves the mapping in workspace.config.json.

Wiring Into Your Agents

Copy the short snippets from examples/AGENTS-snippet.md into each agent's native instruction file:

Agent Entry File
Codex ~/.codex/AGENTS.md
Claude Code ~/.claude/CLAUDE.md
DeepSeek Harness ~/.dsh/AGENTS.md
Antigravity <workspace>/.agents/skills/shared-workspace/SKILL.md (see examples/SKILL.md)

Keep agent entry files thin (commands & triggers only). Do not paste full workspace docs into every system prompt.

Why Not a Vector Database?

Aspect Vector RAG This Approach
Readability Retrieved chunks, opaque ranking Plain Markdown humans read and edit directly
Correctability Requires re-embedding / re-indexing Edit a paragraph or run exp update
Versioning Separate snapshot tooling Native Git diff, blame, and revert
Dependencies Vector store + embedding service Python stdlib only
Failure mode Silently retrieves irrelevant memory Explicit miss — visible and debuggable

Trade-off: keyword, tag, and ID lookup only (no semantic similarity). Ideal for solo developers or small teams managing dozens to hundreds of verified lessons across multiple local agents.

Tests & CI

python -m unittest discover -s tests -v
cd integrations/deepseek-harness && npm run check

15 Python end-to-end tests + 3 Node.js DSH bundle checks run in isolated temp directories on both Ubuntu and Windows in GitHub Actions, including an 8-process concurrent write stress test, lock-timeout verification, and a full MCP stdio JSON-RPC lifecycle test.

License

MIT

Metadata

Release files for agent-shared-workspace 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agent-shared-workspace 0.1.0
File Size Uploaded Provenance Actions
agent_shared_workspace-0.1.0.tar.gz 35.7 kB Without provenance Details for agent_shared_workspace-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agent-shared-workspace 0.1.0
File Interpreter ABI Platform Actions
agent_shared_workspace-0.1.0-py3-none-any.whl Python 3 none any Details for agent_shared_workspace-0.1.0-py3-none-any.whl

Total release size: 58.8 kB

Release files / agent_shared_workspace-0.1.0.tar.gz

Download URL agent_shared_workspace-0.1.0.tar.gz
Size 35.7 kB
Tags Source
SHA-256 checksum
How to use checksums
40236cf323a7866cd071b9e0cb79d05c857b084169e71a156f0a2080f9010c63
BLAKE2b-256 checksum
How to use checksums
4f79d12d08dcfc2d1f3d45a53469b6402dd4bb23ef88d0d84bde0a2233e91f09
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / agent_shared_workspace-0.1.0-py3-none-any.whl

Download URL agent_shared_workspace-0.1.0-py3-none-any.whl
Size 23.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0d09aafa23e91a0d346ab83a31918fa79c1d6e8e1124abda9590a9be64e991cd
BLAKE2b-256 checksum
How to use checksums
ec598d5fa3b3138934d7e9bf1a4d795b28b2f67767d33313f7babc67e7e7b859
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for agent-shared-workspace 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page