Back to README · CLI Reference →
- Rust toolchain (1.88+ for edition 2024)
- SQLite is bundled — no separate install needed
git clone <repo-url>
cd ai-workspace
cargo install --path .The binary ai-workspace is installed to ~/.cargo/bin/.
ai-workspace --version
ai-workspace --help| Concept | Description |
|---|---|
| Project | A directory registered with ai-workspace init |
| Group | A named collection of projects that share context |
| Shared item | A file, directory, or note made available to group members |
| Scope | Visibility level of a note: project (private) or group (shared) |
| Label | An optional human-readable tag on a shared item |
Every shared item has a scope that determines who can see it.
| Scope | Flag | Visible in project | Visible in group |
|---|---|---|---|
| project | --scope project |
Yes | No |
| group | --scope group --group <name> |
No | Yes (all member projects) |
- Project-scoped notes are private to the project that created them. They do not appear in group context. Use these for internal reminders or project-specific details.
- Group-scoped notes are visible to every project in the group. Use these for cross-project conventions, shared credentials locations, deploy instructions, etc.
The default scope for note is group.
Files and directories are always attached to the project that shared them, but they are automatically visible to all groups the project belongs to. There is no --scope flag for share — group visibility is implicit through group membership.
Project A ──┐
├── Group "backend" ──→ sees files from A and B
Project B ──┘
| Item type | Owned by | Visible in project | Visible in group |
|---|---|---|---|
| File / Directory | Project | Yes | Yes (via membership) |
| Project note | Project | Yes | No |
| Group note | Group | No | Yes (all members) |
Use groups for projects that should see each other's shared context. Use service links when one project depends on another service at runtime or operationally:
ai-workspace link add billing-api auth-service --kind depends_onThe link direction is intentional: billing-api --depends_on--> auth-service means auth events affect billing.
Use artifact dependencies when a shared file or directory needs a specific reaction if a service changes:
ai-workspace artifact depends specs/auth.md auth-service --kind references --reaction updateWhen a service changes, create an event and check affected inboxes:
RUST_LOG=debug ai-workspace event create --kind service_changed --source auth-service --title "Auth contract changed"
ai-workspace event inboxRUST_LOG=debug is useful when troubleshooting event impact calculation because it logs link matches and artifact dependency matches. Destroying a project creates a service_deleted event before the project row is removed, so related projects can still inspect the source snapshot and affected artifacts.
cd ~/project-a
ai-workspace init --group backend
cd ~/project-b
ai-workspace init --group backendBoth projects now belong to the backend group.
Key project files (README*, Cargo.toml, package.json, go.mod, etc.) are automatically shared on first init — no manual share needed for common files. This auto-share is skipped when the configured workspace JSON is present.
If the configured workspace JSON exists, init also reads the optional project slug, shared entry kind, and shared entry dependencies metadata. This lets a committed config restore directory shares and artifact dependencies without exporting event history. Use --config .ai/ai-workspace.json or AI_WORKSPACE_CONFIG=.ai/ai-workspace.json if your repo keeps AI files under .ai. The configured JSON path and configured shared paths must resolve inside the project directory; absolute config paths, unsafe relative paths, symlink escapes, and final config-path symlinks are rejected. Config share entries are literal paths, not glob patterns; use "docs" rather than "docs/**" to share a directory. Existing ordinary files at the configured JSON path are not adopted or overwritten.
cd ~/project-a
ai-workspace share src/schema.rs --label "db schema"
ai-workspace share docs/ --label "project docs"# Project-scoped note (only visible in this project's context)
ai-workspace note "Uses PostgreSQL 16" --label "db-note" --scope project
# Group-scoped note (visible to all projects in the group)
ai-workspace note "Deploy to staging before merging" --label "deploy-note" --scope group --group backend# Change note content (notes only)
ai-workspace edit "db-note" --content "Uses PostgreSQL 16 + pgvector"
# Promote a project note to group scope
ai-workspace edit "db-note" --scope group --group backend
# Change just the label
ai-workspace edit "deploy-note" --label "release-checklist"ai-workspace statusai-workspace serveThe server reads JSON-RPC requests from stdin and writes responses to stdout.
The server exposes MCP tools including workspace_context, workspace_read, workspace_search, workspace_search_fulltext, workspace_service_graph, workspace_events, workspace_event_details, list_groups, list_projects, project_tree, and project_grep. The project_tree and project_grep tools let agents navigate any registered project's file tree and search file contents by regex. The project_file_write tool is disabled by default and omitted from tools/list; set AI_WORKSPACE_ALLOW_PROJECT_FILE_WRITE=1 on the MCP server process to expose it intentionally. When enabled, it lets agents create a regular file inside an in-scope project, immediately share it, and index Markdown content. By default, MCP project navigation, full-text file search, direct path reads, and writes hide dotfiles and credential-like paths such as .env, .ssh, .aws, *.pem, and *.key. workspace_read, project_tree, and project_grep can opt in to those paths; workspace_search_fulltext always excludes hidden or credential-like .md paths.
The database is stored at ~/.ai-workspace/workspace.db (all platforms).
Override with the AI_WORKSPACE_DB environment variable:
AI_WORKSPACE_DB=/custom/path/workspace.db ai-workspace statusSet RUST_LOG to control log output:
RUST_LOG=debug ai-workspace status
RUST_LOG=info ai-workspace serve- CLI Reference — All commands and options
- MCP Server — Integrate with AI coding tools
- CLI Reference — Complete command documentation
- MCP Server — MCP tools and integration guide