Claude Code Integration

Toto turns Claude Code into a task management interface. No browser tabs, no context switching. You plan work, track progress, and reconcile commits without leaving the terminal.

See it in action →

This document covers all 12 slash commands, hooks configuration, CLAUDE.md integration, subagent tracking, the optional MCP server, and three complete workflow examples.

Setup

If you haven't set up Toto yet, see Quickstart. You need:

1. Slash commands installed (curl -fsSL https://toto.tech/install | bash)
2. API connection configured (/toto-setup)
3. Connection verified (/toto-status)

Quick Setup — Copy & Paste

Everything you need to get Toto running in Claude Code. Expand each section, copy the contents, and paste into the specified file.

curl -fsSL https://toto.tech/install | bash

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command // \"\"' | grep -q '^git commit' && echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PostToolUse\",\"additionalContext\":\"A git commit was just made. Run /toto-reconcile --depth 5 to match this commit against pending tasks.\"}}' || true",
            "timeout": 5,
            "statusMessage": "Checking for task matches..."
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"Session started. Run /toto-reconcile --depth 50 to catch any unreconciled commits from previous sessions. Also run /toto-status to show current task progress.\"}}'",
            "timeout": 5,
            "statusMessage": "Loading Toto context..."
          }
        ]
      }
    ]
  }
}

## Toto Task Tracking

Track work via Toto. Use these commands:

| Command | Purpose |
|---------|---------|
| `/toto-plan [description]` | Create a list with subtasks |
| `/toto-start [id or text]` | Mark item as in_progress |
| `/toto-done [id or text]` | Mark item as done |
| `/toto-add [task] [--list N]` | Quick-add a single task |
| `/toto-status` | Show current progress |
| `/toto-search [query]` | Search all lists (alias `/ts`) |
| `/toto-reconcile` | Match git commits to tasks |
| `/toto-enrich --all` | Populate bare task metadata |
| `/toto-lint` | Audit board health |
| `/toto-help` | List Toto commands + suggested next action (alias `/th`) |

Track your work via the Toto API:
- Create tasks: POST {BASE_URL}/api/lists/{LIST_ID}/items/batch
  Headers: Authorization: Bearer {TOKEN}, Content-Type: application/json
  Body: {"items": [{"task": "subtask name", "priority": 2}]}

- Start task: POST {BASE_URL}/api/items/{ITEM_ID}/status
  Body: {"status": "in_progress"}

- Finish task: POST {BASE_URL}/api/items/{ITEM_ID}/status
  Body: {"status": "done"}

Create tasks BEFORE starting work. Never create and immediately mark done.
Keep task names short (3-8 words). If the API is unreachable, continue
working and retry later.

// Save to: ~/.claude/skills/toto-config.json
{
  "base_url": "https://toto.tech",
  "token": "toto_your_api_key_here"
}

/toto-status

Slash Commands

/toto-setup -- Configure API Connection

Sets up the API connection for all other slash commands.

Usage: /toto-setup

Prompts for your Toto URL and API token, saves them to ~/.claude/skills/toto-config.json, and tests the connection.

> /toto-setup
Base URL: https://toto.tech
Token: toto_abc123...
Connection verified. Setup complete.

/toto-plan -- Create a List with Subtasks

The primary way to start new work. Parses a description into a Toto list with actionable subtasks. Each task gets a description, category, priority, and reconciliation metadata.

Usage: /toto-plan [description of what you're building]

> /toto-plan Add Google OAuth login flow
Created list: "Google OAuth" (#42)
  - #201 "Add OAuth middleware" (backend, priority: 3)
  - #202 "Create user model" (schema, priority: 3)
  - #203 "Build login redirect flow" (backend, priority: 2)
  - #204 "Add session persistence" (backend, priority: 2)
  - #205 "Write OAuth tests" (test, priority: 1)

Details:

• Creates 3-10 items per list (enough signal, not too noisy)
• Items are ordered by dependency -- foundational work first, polish last
• Every item includes metadata for Semantic Reconciliation
• See Task Metadata for the metadata schema

/toto-add -- Quick-Add a Single Task

Adds a single task to a Toto list. Generates reconciliation metadata even for quick-add items.

Usage: /toto-add [task text] [--list LIST_ID]

> /toto-add Fix edge case in auth flow --list 42
Added: #206 "Fix edge case in auth flow" to list "Google OAuth"

If --list is omitted, uses the most recently active list or asks you to pick one.

/toto-start -- Mark Item as In-Progress

Sets a task's status to in_progress. This triggers the glow animation on the dashboard -- the card pulses to show active work.

Usage: /toto-start [item_id or description]

> /toto-start Add OAuth middleware
Started: #201 "Add OAuth middleware" (in_progress)

Accepts an item ID or a text search against pending items.

/toto-done -- Mark Item as Done

Sets a task's status to done. Triggers the completion animation on the dashboard. If no argument is given, marks the current in_progress item as done.

Usage: /toto-done [item_id or description]

> /toto-done
Done: #201 "Add OAuth middleware" (3 remaining)

Defaults to the most recent in_progress item when called with no arguments.

/toto-status -- Show Current Progress

Displays the state of your active lists, grouped by status with a done/remaining summary.

Usage: /toto-status

## List: "Google OAuth" (#42)

Active:
  > #202 "Create user model" (in_progress)

Pending:
  - #203 "Build login redirect flow" (priority: medium)
  - #204 "Add session persistence" (priority: medium)
  - #205 "Write OAuth tests" (priority: low)

Done: 1/5 complete

/toto-reconcile -- Match Git Commits to Tasks

Reads recent git history and uses multi-signal matching to compare each commit against pending and in-progress tasks. Presents confident matches and possible matches for confirmation before marking anything done.

Usage:

• /toto-reconcile -- match last 50 commits
• /toto-reconcile --depth 5 -- match last 5 commits (use after a single commit)
• /toto-reconcile --depth 50 -- deeper sweep for older commits
• /toto-reconcile --list LIST_ID -- scope to a specific list

=== Reconciliation Results ===

Commit a1b2c3d "refactor auth flow to use session cookies"
  Files: app/api/auth_web.py, app/services/auth_service.py, tests/test_auth.py

  [MATCH] "Add OAuth middleware" (list: Google OAuth, id: 201)
    Confident match across file paths, keywords, and component signals.

  [MAYBE] "Write auth tests" (list: Google OAuth, id: 205)
    Possible match — partial file and keyword overlap.

Mark matched tasks as done? List the IDs to confirm, or say "all" / "none".

What the signals mean:

• File path overlap -- strongest signal. If a task predicts app/api/auth.py will change and the commit touches it, that's a strong match.
• Keyword match -- technical terms in the commit message that match task keywords.
• Component alignment -- task's component name appears in file paths or commit message.
• Scope match/mismatch -- a backend task that only touches .js files gets penalized.

Tasks need metadata for accurate matching. Bare tasks (no metadata) fall back to title-only matching, which rarely produces confident matches. See Task Metadata.

/toto-enrich -- Populate Bare Tasks with Metadata

Retroactively generates descriptions and reconciliation metadata for existing tasks that are missing them. Shows a before/after preview for approval before writing.

Usage:

• /toto-enrich --list LIST_ID -- enrich bare tasks in a specific list
• /toto-enrich --all -- scan all lists for bare tasks
• /toto-enrich --dry-run -- preview without writing

=== Enriching "Google OAuth" (2 bare items) ===

1. "Add session persistence"

   BEFORE: (no description, no metadata)

   AFTER description:
   > Implement persistent session storage so users stay logged in
   > across browser restarts. Use secure httponly cookies with
   > configurable expiry.

   AFTER metadata:
     component: auth-middleware
     files: [app/services/auth_service.py, app/api/auth_web.py]
     keywords: [session, cookie, httponly, persistence, expiry]
     scope: backend
     intent: Users remain logged in across browser sessions

Apply all? [y/N]

Metadata updates are additive -- existing values are preserved and extended, never overwritten (except intent, which can be rewritten when understanding improves).

/toto-lint -- Audit Board Health

Read-only audit of all non-done tasks. Reports missing metadata, stale items, generic keywords, scope mismatches, and reconciliation readiness. Never modifies data.

Usage: /toto-lint

=== Toto Lint Report ===
Scanned: 25 lists, 150 items (120 non-done)

CRITICAL (2):
  ! [Google OAuth] "Add OAuth flow" -- in_progress for 8 days
  ! [Auth Rework] "Session middleware" -- metadata.files: auth_web.py does not exist

WARNING (35):
  ~ 28 items have no metadata (cannot be reconciled)
  ~ 4 items have no description
  ~ 2 items have generic keywords: "code", "system"

INFO (12):
  . 12 items have no category tag
  . 3 items have intent < 20 chars

--- Summary ---
Metadata coverage: 92/120 items (77%) -- target: >90%
Description coverage: 88/120 items (73%) -- target: >90%
Reconciliation-ready: 85/120 items (71%)

Suggestion: Run /toto-enrich --all to populate bare items.

/toto-search -- Search Across Lists

Searches every list for items matching a literal string, regex, or glob. Searches task titles, descriptions, categories, and metadata. Returns results grouped by list. Aliased as /ts for short-hand.

Usage: /toto-search [query]

> /toto-search oauth
=== List: "Google OAuth" (#42) ===
  - #201 "Add OAuth middleware" (in_progress)
  - #205 "Write OAuth tests" (pending)

=== List: "Auth Rework" (#19) ===
  - #88 "Migrate OAuth callback to /v2" (pending)

/toto-help -- List Commands and Suggest Next Action

Prints every Toto slash command with a one-line summary and looks at the conversation context to suggest the best next action (e.g. "you just committed — try /toto-reconcile --depth 5"). Aliased as /th.

Usage: /toto-help or /th

/session -- Write Session Summary (gstack, optional)

/session is provided by gstack, not Toto, but pairs naturally with the workflow. It generates a session summary from git history, saves it to a documentation vault, and creates a Toto list from open/carry-forward items.

Usage:

• /session -- summarize this work session
• /session [focus] -- emphasize a specific area

A "session" is a continuous block of work, dated by when it started.

Hooks Configuration

Two hooks in ~/.claude/settings.json automate the integration. They fire automatically -- you never invoke them manually.

Post-Commit Hook

After every git commit, prompts Claude to run reconciliation against the last 5 commits. Catches task matches in real-time as you work.

Session Start Hook

When a new Claude Code session starts, prompts Claude to run a deeper reconciliation sweep (last 50 commits) and show current task status. Catches commits from previous sessions that were never reconciled.

Configuration

Add to ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command // \"\"' | grep -q '^git commit' && echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PostToolUse\",\"additionalContext\":\"A git commit was just made. Run /toto-reconcile --depth 5 to match this commit against pending tasks.\"}}' || true",
            "timeout": 5
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":\"Session started. Run /toto-reconcile --depth 50 to catch any unreconciled commits. Also run /toto-status to show current task progress.\"}}'",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Note: > The PostToolUse hook only fires on git commit commands run through Claude Code's Bash tool. Commits made in a separate terminal won't trigger it. Use /toto-reconcile --depth 50 to catch those.

CLAUDE.md Integration

Add Toto tracking to any project by adding this to its CLAUDE.md:

## Toto Task Tracking

Track work via Toto. Use these commands:

| Command | Purpose |
|---------|---------|
| `/toto-plan [description]` | Create a list with subtasks |
| `/toto-start [id or text]` | Mark item as in_progress |
| `/toto-done [id or text]` | Mark item as done |
| `/toto-add [task] [--list N]` | Quick-add a single task |
| `/toto-status` | Show current progress |
| `/toto-search [query]` | Search all lists (alias `/ts`) |
| `/toto-reconcile` | Match git commits to tasks |
| `/toto-enrich --all` | Populate bare task metadata |
| `/toto-lint` | Audit board health |
| `/toto-help` | List Toto commands + suggested next action (alias `/th`) |

Subagent Tracking

When spawning subagents for work, include a tracking snippet so they report progress via the API. Read ~/.claude/skills/toto-config.json for the current base_url and token, then append this to the agent prompt:

## Toto Task Tracking

Track your work via the Toto API. Config: base_url={BASE_URL}, token={TOKEN}.

CRITICAL: Create tasks BEFORE you start working, not after. The lifecycle is:
create -> in_progress -> done, at the right time.

Step 1: At the START of your work, create ALL your planned subtasks:
  curl -s -X POST "{BASE_URL}/api/lists/{LIST_ID}/items/batch" \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{"items": [{"task": "subtask 1"}, {"task": "subtask 2"}, ...]}'

Step 2: When you BEGIN working on a subtask, set it to in_progress:
  curl -s -X POST "{BASE_URL}/api/items/{ITEM_ID}/status" \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{"status": "in_progress"}'

Step 3: When you FINISH a subtask, mark it done:
  curl -s -X POST "{BASE_URL}/api/items/{ITEM_ID}/status" \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{"status": "done"}'

Replace {BASE_URL}, {TOKEN}, and {LIST_ID} with actual values from the config.

Rules for subagents:

• Create tasks BEFORE starting work, never create-and-immediately-done
• Keep task names short (3-8 words)
• If the API is unreachable, continue working and retry tracking later
• Aim for 3-12 items per list

MCP Server (Optional)

If you prefer native tool calls (mcp__toto__add_item) instead of curl-based slash commands, configure the MCP server:

// .mcp.json in project root or ~/.claude/mcp.json
{
  "mcpServers": {
    "toto": {
      "command": "toto-mcp",
      "env": {
        "TOTO_URL": "https://toto.tech",
        "TOTO_TOKEN": "toto_your_api_key_here"
      }
    }
  }
}

Install via:

pipx install toto-cli

This installs both the toto CLI and the toto-mcp MCP server.

The API-first approach (slash commands using curl) is recommended. It's more reliable across sessions and doesn't require MCP server setup. The MCP server is a convenience layer for tools that support native MCP integration.

Workflow Examples

Workflow 1: Starting a New Feature

The standard flow for planned work.

1. /toto-plan "Add Google OAuth"
   -> Creates list "Google OAuth" (#42) with 5 enriched tasks
   -> Each task has description, category, priority, and metadata

2. /toto-start "Add OAuth middleware"
   -> Task #201 glows on the dashboard

3. Write code, run tests, commit.
   -> git commit fires the PostToolUse hook
   -> Claude runs /toto-reconcile --depth 5
   -> Commit matches task #201 as a confident match
   -> You confirm: "201"
   -> Task #201 marked done with completion animation

4. /toto-start "Create user model"
   -> Next task begins glowing

5. Repeat until list is complete.

6. /session
   -> Writes session summary to vault
   -> Open items become a "Next" list on the dashboard

Workflow 2: Session Cleanup

Catching up after a burst of work, or wrapping up a long session.

1. /toto-reconcile --depth 50
   -> Sweeps last 50 commits against all pending/in_progress tasks
   -> Shows confident and possible matches
   -> Confirm which to mark done

2. /toto-lint
   -> Shows board health: missing metadata, stale items
   -> Reports reconciliation readiness percentage

3. /toto-enrich --all
   -> Finds bare tasks (no description or metadata)
   -> Generates rich content for each, shows before/after
   -> You approve which to apply

4. /session
   -> Writes comprehensive session summary
   -> Creates "Next" list from open items

Workflow 3: Board Maintenance

Periodic hygiene to keep the task board useful.

1. /toto-lint
   -> CRITICAL: items in_progress for 8+ days, stale file paths
   -> WARNING: 28 items with no metadata, generic keywords
   -> Summary: 71% reconciliation-ready (target: >90%)

2. /toto-enrich --list 42
   -> Enrich bare tasks in a specific list
   -> Preview and approve enrichments

3. /toto-status
   -> See current active work and progress across lists

4. Clean up stale lists:
   -> Mark abandoned in_progress items as deferred or done
   -> Delete empty or completed lists

Architecture Reference

You (in Claude Code)
  |
  |-- Slash commands (/toto-plan, /toto-done, etc.)
  |     Skills: ~/.claude/skills/toto-*/SKILL.md
  |     Config: ~/.claude/skills/toto-config.json
  |
  |-- MCP tools (add_item, set_status, etc.)
  |     Config: .mcp.json or ~/.claude/mcp.json
  |
  |-- Hooks (post-commit, session-start)
  |     Config: ~/.claude/settings.json
  |
  v
Toto API (REST)
  |
  |-- REST: /api/lists, /api/items, /api/items/{id}/status
  |-- SSE: real-time events for dashboard animations
  |-- Auth: Bearer token (toto_ prefix, read/write/admin scopes)
  |
  v
Toto Dashboard (web UI)
  |-- Real-time task cards with glow and completion animations
  |-- Rich card UI with expandable descriptions
  |-- FX sidebar for animation controls

Further Reading

• Task Metadata -- Write metadata that makes reconciliation accurate
• Semantic Reconciliation -- How commit-to-task matching works
• API Reference -- Full REST API for custom integrations
• VIM Mode -- Keyboard navigation for the dashboard