Agent Collaboration

Dojo is built from the ground up for AI agent collaboration. Agents are first-class participants with their own workspaces, structured commits, and full API access.

The workspace model

Agents work through remote workspaces — isolated sandboxes on the server. No local checkout needed. Each workspace:

• Is based on a specific commit (usually the main tip)
• Maintains an overlay of changed files
• Supports multiple commits within a session
• Can be submitted as a stack for review

# Create a workspace
dojo workspace create --name "feature-auth" --agent "claude"

# Write files
dojo workspace write <ws-id> src/auth.ts

# Commit
dojo workspace commit <ws-id> -m "Implement OAuth flow"

# Submit for review
dojo workspace submit <ws-id> -t "Add authentication"

Why workspaces, not branches?

Workspaces solve problems that branches can’t:

• No filesystem races — multiple agents can work simultaneously without local file conflicts
• Instant creation — no git clone, no checkout. Workspace is ready in milliseconds
• Built-in isolation — each workspace has its own overlay; changes are invisible to other workspaces
• Path locking — prevent two agents from editing the same files
• Conflict detection — check for overlapping changes before submitting

Multi-agent patterns

Parallel agents on separate features

The simplest pattern: each agent gets its own workspace for a different feature.

Agent A → workspace "auth-system" → src/auth/*
Agent B → workspace "dashboard-ui" → src/components/*
Agent C → workspace "api-endpoints" → src/routes/*

No coordination needed — workspaces are naturally isolated.

Relay pattern (sequential handoff)

One agent starts work, another picks it up:

1. Agent A creates a workspace, writes code, commits
2. Agent B creates a new workspace based on Agent A’s commit
3. Agent B continues where Agent A left off

# Agent A works
dojo workspace create --name "auth-v1" --agent "claude"
dojo workspace commit ws_a -m "Add OAuth skeleton"

# Agent B continues from Agent A's commit
dojo workspace create --name "auth-v2" --agent "gemini" --base-commit <agent-a-commit>

Review agent pattern

One agent writes code, another reviews it:

1. Author agent creates workspace, writes code, submits stack
2. Review agent reads the stack diff and leaves comments
3. Author agent addresses feedback

Dojo’s review API supports this natively.

Searching code

Agents can search repository contents via the API or the pi-dojo tool:

# Search via API
GET /api/repos/owner/name/search?q=handleAuth&ref=main

# Search within a workspace (includes uncommitted overlay files)
GET /api/repos/owner/name/workspaces/ws_id/search?q=handleAuth

Search is powered by FTS5 with ranked results, snippet extraction, and path filtering. See the Search API for full details.

Browsing code

Agents can browse the file tree without downloading the entire repo:

# List root directory
GET /api/repos/owner/name/tree?ref=main

# List subdirectory
GET /api/repos/owner/name/tree?ref=main&path=src/components

# Recursive listing
GET /api/repos/owner/name/tree?ref=main&path=src&recursive=true

# Read a specific file
GET /api/repos/owner/name/file/src/auth.ts?ref=main

See the Tree Browsing API for details.

Intent metadata

Dojo commits support structured metadata for agent traceability:

{
  "message": "Add user model",
  "intent": {
    "goal": "Create database schema for users",
    "plan": "Define TypeScript types, create Drizzle schema, add migration",
    "confidence": "high",
    "agent": "claude-code"
  }
}

This metadata is:

• Stored on the commit in commit_metadata
• Visible in the web UI commit view
• Queryable via API (/api/repos/.../commits?meta.intent.agent=claude)
• Preserved through rebases and rewrites

Scoped API keys

Create restricted API keys for agents to limit what they can do:

POST /api/keys
{
  "name": "agent-claude",
  "scopes": ["repo:read", "workspace:write", "stack:write"]
}

This gives the agent read access to the repo and the ability to create workspaces and submit stacks, but not modify refs directly or change settings. See the API Overview for all available scopes.

Activity heatmap

The Dojo web UI shows a dual-color activity heatmap on repository pages:

• 🟢 Green — human contributions
• 🟣 Purple — agent contributions

This gives an at-a-glance view of who’s contributing what, and how active the repo is.

pi-dojo integration

If you’re using pi as your agent harness, the pi-dojo extension provides native tools:

Tool	Description
dojo_status	Repository status overview
dojo_commit	Create commits with intent metadata
dojo_workspace	Full workspace management (create, write, read, commit, submit, search, tree)
dojo_stacks	List, show, and submit stacks
dojo_review	Code review (approve, reject, comment)
dojo_history	Log, show, evolution, ops
dojo_sync	Push and pull
dojo_rewrite	Describe, split, reorder, undo

Install pi-dojo in your .pi/settings.json:

{
  "extensions": ["../packages/pi-dojo"]
}

Best practices

1. Use workspaces — avoid filesystem races with other agents and humans
2. Small, focused commits — easier to review and revert
3. Include intent metadata — explain your reasoning for reviewers
4. Check for conflicts before submitting stacks
5. Use scoped API keys — principle of least privilege
6. Search before writing — use the search API to understand existing code
7. Browse the tree — understand the project structure before making changes