AI Workspace

Give your AI agents memory that spans across projects.

AI coding agents (Claude Code, Cursor, Windsurf, etc.) are powerful — but they only see one project at a time. When your work involves a shared API contract, a common deploy process, or a monorepo split into microservices, the agent starts every conversation blind to the bigger picture.

AI Workspace fixes that. It's a lightweight CLI + MCP server that lets you share files, directories, and notes across related projects. Your agents get cross-project context automatically — no copy-pasting, no symlinks, no custom prompts.

It also includes a local Rust-only CodeGraph MVP: registered projects can index shared Rust source scopes into SQLite as files, symbols, and call relationships, then expose that structure to agents through CLI and MCP tools.

How it works

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  project-api │     │ project-web  │     │ project-docs │
│              │     │              │     │              │
│  schema.rs ──┼─┐   │              │     │              │
│  notes ──────┼─┤   │  notes ──────┼─┐   │  guides/ ────┼─┐
└──────────────┘ │   └──────────────┘ │   └──────────────┘ │
                 │                    │                    │
                 └────────┬───────────┘────────────────────┘
                          │
                    ┌─────▼──────┐
                    │  "backend" │  ← group
                    │   group    │
                    └─────┬──────┘
                          │
                    ┌─────▼──────┐
                    │ MCP Server │  ← ai-workspace serve
                    │  (stdio)   │
                    └─────┬──────┘
                          │
                    ┌─────▼──────┐
                    │  AI Agent  │  sees files, dirs & notes
                    │            │  from all 3 projects
                    └────────────┘

Group projects together. Share files and notes. Your agent sees everything.

Quick Start

Install

cargo install --path .

Requires Rust 1.88+ (edition 2024). SQLite is bundled — no extra dependencies.

Set up projects

# Register two projects in the same group
cd ~/api
ai-workspace init --group backend

cd ~/web
ai-workspace init --group backend

Share context

cd ~/api
ai-workspace share src/schema.rs --label "db schema"
ai-workspace note "Deploy: run migrations before release" --group backend

Now any agent working in ~/web can read schema.rs and the deploy note from ~/api.

Connect to your agent

Claude Code:

claude mcp add --scope user ai-workspace -- ai-workspace serve

Other MCP clients (Cursor, Windsurf, Claude Desktop, etc.):

{
  "mcpServers": {
    "ai-workspace": {
      "command": "ai-workspace",
      "args": ["serve"]
    }
  }
}

That's it. The agent now has access to 17 MCP tools by default: workspace_context, workspace_read, workspace_search, workspace_search_fulltext, workspace_service_graph, workspace_events, workspace_event_details, list_groups, list_projects, project_tree, project_grep, and the Rust CodeGraph tools codegraph_status, codegraph_search, codegraph_node, codegraph_callers, codegraph_callees, and codegraph_context. During MCP initialization, AI Workspace also provides startup instructions that guide capable agents to call workspace_context when project/group context may matter, prefer shared context and CodeGraph tools before broad scans, and update shared Markdown context only for durable project knowledge. By default, project navigation, full-text file search, and direct path reads hide dotfiles and credential-like paths such as .env, .ssh, .aws, *.pem, and *.key. workspace_read, project_tree, and project_grep support explicit opt-in flags; workspace_search_fulltext is stricter and never returns hidden or credential-like .md paths.

By default, MCP tools expose only files, directories, and notes that you explicitly share. Full project tree, grep, path reads, and absolute project path metadata require opting in with AI_WORKSPACE_ALLOW_PROJECT_WIDE_TOOLS=1 on the MCP server process.

File writes are disabled by default. To expose project_file_write, set AI_WORKSPACE_ALLOW_PROJECT_FILE_WRITE=1 on the MCP server process intentionally. This opt-in is separate from AI_WORKSPACE_ALLOW_PROJECT_WIDE_TOOLS; enabling project-wide reads/search does not enable filesystem writes.

{
  "mcpServers": {
    "ai-workspace": {
      "command": "ai-workspace",
      "args": ["serve"],
      "env": {
        "AI_WORKSPACE_ALLOW_PROJECT_FILE_WRITE": "1"
      }
    }
  }
}

You can also restrict the MCP server to part of the local workspace:

ai-workspace serve --scope current-project
ai-workspace serve --group backend
ai-workspace serve --project api

The same modes are available through AI_WORKSPACE_SCOPE=global|current-project|group|project, AI_WORKSPACE_SCOPE_GROUP, and AI_WORKSPACE_SCOPE_PROJECT. CLI flags override env vars. Scoping filters metadata, search, service graphs, events, reads, tree, and grep; AI_WORKSPACE_ALLOW_PROJECT_WIDE_TOOLS=1 only broadens filesystem access inside the configured MCP scope.

AI Factory integration

AI Workspace works well with AI Factory projects. Use the preset once per project to create and share the baseline .ai-factory context files:

ai-workspace init --preset ai-factory

For Rust projects, share the source scopes you want CodeGraph to expose through MCP, then build the graph:

ai-workspace share dir src
# or, for Rust workspaces:
ai-workspace share dir crates
ai-workspace codegraph sync

Then ask your agent to persist an AI Factory rule with the aif-rules skill:

After each implementation, run `ai-workspace codegraph sync` so the local CodeGraph stays current.

With that rule in place, AI Factory agents refresh CodeGraph after implementation work, and the MCP tools (codegraph_context, codegraph_search, codegraph_callers, and codegraph_callees) can use fresh symbol and call data before falling back to grep. If your team intentionally indexes the whole Rust project instead of shared scopes, make the rule ai-workspace codegraph sync --full-project and run the MCP server with AI_WORKSPACE_ALLOW_PROJECT_WIDE_TOOLS=1.

Example Prompts

Once connected, you can talk to your AI agent naturally. Here are some examples:

Discover context:

• "What shared context do I have from other projects?"
• "Show me all projects and groups in my workspace"
• "What files are shared in the backend group?"

Read shared files:

• "Read the shared database schema from the api project"
• "Show me the deploy guide shared by the infra team"
• "What's in the shared config directory?"

Write shared files:

• "Create docs/agent-notes/auth.md in the api project and share it"
• "Save this context as docs/generated/context.md in project 2"

Search notes:

• "Search workspace notes for migration instructions"
• "Are there any shared notes about the deploy process?"
• "Find notes mentioning staging environment"

Navigate shared project files:

• "Show me the shared file tree of the api project"
• "List the files under the shared src/ directory in project 2"
• "Search the api project's shared files for any function that mentions 'auth'"
• "Grep the web project's shared files for TODO comments"

Use Rust CodeGraph:

• "Use CodeGraph to find callers of the auth token parser"
• "Get compact code context for changing the workspace search flow"
• "Search indexed Rust symbols named sync_project before grepping files"

Cross-project tasks:

• "I'm building a new endpoint — check the shared API schema and follow the same patterns"
• "Before I refactor this model, check if other projects share files that depend on it"
• "Read the shared style guide and apply it to this component"

The agent will automatically call the right MCP tools (workspace_context, workspace_read, workspace_search, workspace_search_fulltext, workspace_service_graph, workspace_events, workspace_event_details) to answer these.

CLI at a glance

Team Sharing

Share your workspace config with your team by committing .ai-workspace.json to the repo:

# One-time: export current config
ai-workspace export

# Commit the file
git add .ai-workspace.json
git commit -m "chore: add shared workspace config"

When a teammate clones the repo and runs init, they automatically get the same groups, stable slug, shared files/directories, notes, and artifact dependency metadata:

cd ~/cloned-repo
ai-workspace init
# → picks up name, slug, groups, shares, notes, and dependencies from the configured workspace JSON

The --name flag overrides the name from .json, and --group is additive. Running sync also reconciles the database with the configured workspace JSON if present.

.ai-workspace.json path style

Use forward slashes in committed .ai-workspace.json share paths, even on Windows. Shared paths from config must exist, stay inside the project directory, and be project-relative literal file or directory paths:

{
  "share": [
    "examples",
    "docs",
    "docs/README.md"
  ]
}

Do not use glob patterns or Windows separator/trailing-slash style in committed configs:

{
  "share": [
    "docs/**",
    "examples\\"
  ]
}

To share everything under docs, share the directory with "docs" instead of "docs/**". Backslash or trailing-slash entries may be normalized for compatibility when imported, but they are not the canonical style for committed config. ai-workspace export writes normalized / paths without trailing directory slashes, such as "docs/README.md" and "examples".

Artifact dependency sync is partial: if a share object omits dependencies, existing dependency rows for that share are left unchanged. To manage dependencies declaratively, include dependencies; an explicit empty array removes all dependencies for that share:

{
  "path": "docs/auth.md",
  "kind": "file",
  "dependencies": []
}

The workspace JSON exports project-scoped configuration only: group notes and event history stay local and are intentionally not exported.

If your repo keeps AI-related files under a dedicated directory, pass a custom config path. The path must be relative and remain inside the project root; absolute paths, .., backslashes on Unix, symlink escapes, and final config-path symlinks are rejected. Existing files at that path are only updated when they are already recognizable ai-workspace configs, so ordinary files such as README.md or package.json are not overwritten by a mistaken config path:

ai-workspace --config .ai/ai-workspace.json export
AI_WORKSPACE_CONFIG=.ai/ai-workspace.json ai-workspace init

Documentation

Installation

curl -fsSL https://github.com/lee-to/ai-workspace/releases/latest/download/ai-workspace-aarch64-apple-darwin.tar.gz | sudo tar xz -C /usr/local/bin

curl -fsSL https://github.com/lee-to/ai-workspace/releases/latest/download/ai-workspace-x86_64-apple-darwin.tar.gz | sudo tar xz -C /usr/local/bin

curl -fsSL https://github.com/lee-to/ai-workspace/releases/latest/download/ai-workspace-x86_64-unknown-linux-gnu.tar.gz | sudo tar xz -C /usr/local/bin

curl -fsSL https://github.com/lee-to/ai-workspace/releases/latest/download/ai-workspace-aarch64-unknown-linux-gnu.tar.gz | sudo tar xz -C /usr/local/bin

$release = "https://github.com/lee-to/ai-workspace/releases/latest/download"
Invoke-WebRequest -Uri "$release/ai-workspace-x86_64-pc-windows-msvc.zip" -OutFile ai-workspace.zip
Invoke-WebRequest -Uri "$release/SHA256SUMS.txt" -OutFile SHA256SUMS.txt

$match = Select-String -Path SHA256SUMS.txt -Pattern "ai-workspace-x86_64-pc-windows-msvc.zip"
if (-not $match) { throw "Checksum entry not found for ai-workspace.zip" }

$expected = ($match.Line -split '\s+')[0].ToLowerInvariant()
$actual = (Get-FileHash ai-workspace.zip -Algorithm SHA256).Hash.ToLowerInvariant()
if ($actual -ne $expected) { throw "Checksum mismatch for ai-workspace.zip" }

Expand-Archive ai-workspace.zip -DestinationPath "$env:USERPROFILE\bin" -Force

Every release publishes SHA256SUMS.txt; verify the archive before expanding it. Add %USERPROFILE%\bin to PATH if needed.

git clone https://github.com/lee-to/ai-workspace.git
cd ai-workspace
cargo install --path .

Requires Rust 1.88+ (edition 2024). SQLite is bundled — no extra dependencies.

Update

ai-workspace update

Downloads the latest release from GitHub and replaces the current binary. No Rust or Cargo required.

License

MIT