Workflows

Dojo supports multiple workflows out of the box. Pick what fits your team, or mix and match — they all compose naturally on top of the same primitives.

Linear workflow

The simplest approach — commit directly to main and push. Great for solo projects, prototyping, or small teams that don’t need formal review.

# Edit files — @ auto-snapshots on every command
echo "feature" > feature.rs
dojo st                    # shows what @ changes vs parent
dojo ci -m "add feature"   # describe @, new empty @ created on top
dojo push                  # pushes commits + advances main on remote

Pull to stay in sync:

dojo pull

That’s it. Your working copy (@) always sits on top of the main bookmark. dojo commit describes @ and creates a new empty @ on top. dojo push syncs everything.

Tip

Use dojo bm list to see which bookmark you’re on. The @ marker shows where your working copy sits.

Feature bookmark workflow

Work on a separate bookmark to isolate changes before they’re ready. Good for larger features or when you want to keep main clean.

# Create a feature bookmark (branches from current commit)
dojo bm set my-feature

# Make commits — they land on my-feature, not main
dojo ci -m "wip: auth module"
dojo ci -m "feat: complete auth"

# Check bookmark state
dojo bm list
#   main       abc123  previous commit
# @ my-feature def456  feat: complete auth

When you’re done, move main forward and push:

dojo bm set main          # points main at current commit
dojo push                  # pushes everything

Or, if you want to go through review first, submit a stack:

dojo stack submit --title "Auth module"

Stack-based review

This is where Dojo really shines. A stack is Dojo’s replacement for pull requests — a named range of commits defined by a bookmark and a base commit.

Why stacks instead of PRs?

• Commits are the unit of review — each commit can be reviewed, approved, and commented on individually. No giant diffs.
• Stacks evolve — amend, rebase, or split commits and reviewers see only what changed since their last look (--delta).
• No branch juggling — a stack is just a bookmark pointing at the tip. No source/target branch confusion.
• Agents can submit too — a remote workspace can submit a stack, same as a human.

The full flow

# 1. Create a bookmark for your work
dojo bm set my-feature

# 2. Make commits (they advance the bookmark)
dojo ci -m "refactor auth types"
dojo ci -m "add token validation"
dojo ci -m "wire up middleware"

# 3. Submit for review (pushes commits + creates/updates the stack)
dojo stack submit --title "Auth overhaul"

# 4. Teammates review — on web, CLI, or API
#    - expand each commit, see file-level diffs
#    - leave inline comments on specific lines
#    - approve or request changes

# 5. Address feedback, amend, resubmit
dojo desc -m "better commit message"
dojo stack submit                    # updates the existing stack

# 6. Merge when approved
dojo stack merge 1

# 7. Pull to sync locally
dojo pull

Managing stacks

dojo stack list                # list all stacks (open, merged, closed)
dojo stack show 1              # detail view: commits, comments, review status
dojo stack comment 1 "lgtm!"  # leave a general comment
dojo stack merge 1             # merge into target (checks review requirements)

Note

Merge is blocked until review requirements are met — minimum approvals, no stale reviews, all comments resolved.

Code review

Dojo has a full review system. CLI, web, and API are all first-class. Reviews track what each reviewer has seen, detect stale approvals, and enforce merge requirements.

# Review from the CLI
dojo review list                     # stacks awaiting review
dojo review show 1                   # review overview
dojo review diff 1                   # full diff
dojo review diff 1 --delta           # only changes since your last look

# Leave feedback
dojo review approve 1               # approve the stack
dojo review approve 1 --commit abc  # approve a specific commit
dojo review reject 1 -m "needs error handling"
dojo review comment 1 -m "consider using a LRU cache"

# Check status
dojo review status                   # current bookmark's stack
dojo review comments 1 --unresolved  # only open threads

The web UI gives you:

• Unified and split diff views with syntax highlighting
• Inline commenting — click any diff line to leave a comment
• Resolve/reopen comment threads
• Approve, reject, and merge buttons

When a reviewer’s last-seen commit is rewritten, their approval becomes stale — they need to re-review. Inline comments on rewritten files are flagged as “may be addressed.”

Agent workflow

AI agents are first-class contributors. They get their own scoped tokens, isolated workspaces, and their commits carry structured intent metadata.

How it works

1. Register an agent — create a scoped identity with its own API token
2. Create a workspace — an isolated sandbox where the agent reads, writes, and commits
3. Work remotely — no local clone needed. Everything happens via the API
4. Submit for review — the agent’s stack goes through the same review process as human code

# Register an agent identity
dojo agent register claude-code --version 3.5

# Create an isolated workspace
dojo ws create --name refactor-auth --agent claude-code

# Work in the workspace (all remote, no local checkout)
dojo ws write <ws_id> src/auth.rs
dojo ws write <ws_id> src/auth_test.rs
dojo ws status <ws_id>

# Commit with intent metadata
dojo ws commit <ws_id> -m "refactor: extract auth module" \
  --intent intent.goal="Simplify auth" \
  --intent intent.confidence="high"

# Check for conflicts with other agents
dojo ws check-conflicts <ws_id>

# Submit as a stack for review
dojo ws submit <ws_id> -t "Auth refactor"

Intent metadata

Every commit can carry structured metadata — what the agent was trying to do, how confident it was, and what plan it followed:

dojo ci -m "implement caching" \
  --intent-goal "Add Redis caching layer" \
  --intent-plan "1. Add cache client 2. Wrap DB queries 3. Add TTL config" \
  --intent-confidence "high" \
  --intent-agent "claude-code"

View metadata on any commit:

dojo show --meta           # current commit with metadata
dojo evolution <commit>    # full predecessor chain with metadata

This makes agent contributions auditable — you can always trace back why an agent made a change, not just what it changed.

Conflict detection

Multiple agents working on the same repo? Dojo detects conflicts before they become problems:

dojo ws check-conflicts <ws_id>

This checks the workspace against all other active workspaces and flags overlapping file changes before you commit.

History rewriting

Dojo treats history as a living thing. Commits have predecessors, and rewrites are tracked — so you can always see how a change evolved.

Split commits

Break a large commit into smaller, reviewable pieces:

# Split by file groups
dojo split --spec 'auth.rs:auth changes' --spec 'db.rs:database changes'

# Or use AI to suggest a decomposition
dojo decompose <commit>
dojo decompose <commit> --apply   # auto-apply the suggestion

Reorder commits

Rearrange commits in a chain (with proper 3-way merge):

dojo reorder <id1> <id2> <id3>

Amend and undo

dojo desc -m "better message"    # amend commit message
dojo undo                         # undo last operation
dojo ops log                      # see full operation history

Tip

dojo undo works on any operation — commits, rebases, splits, reorders. The operation log tracks everything.

Next steps

• Explore Stacks to understand the review model in depth
• Read about Agent Collaboration for multi-agent patterns
• See the CLI Reference for the full command list