Docs API Dashboard

FAQ and Troubleshooting

Common issues and clear solutions. If your problem isn't here, check the API Reference for endpoint details or test your connection with a manual curl.

Setup Issues

"Token is empty" / "Run /toto-setup first"

The config file at ~/.claude/skills/toto-config.json is missing or has an empty token.

Fix: Run /toto-setup in Claude Code and enter your Toto URL and API token.

If the file exists but is empty or malformed, delete it and re-run setup:

rm ~/.claude/skills/toto-config.json

Skills Not Appearing in Claude Code

Claude Code discovers skills by looking for SKILL.md files inside directories under ~/.claude/skills/.

Check:

# Do the directories exist?
ls ~/.claude/skills/toto-*/

# Does each have a SKILL.md?
ls ~/.claude/skills/toto-plan/SKILL.md

Common causes:

Fix: Re-run the installer:

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

Then restart Claude Code.

API Connection Failing

Diagnose: Test the connection directly:

curl -s -H "Authorization: Bearer toto_your_token" \
  https://toto.tech/api/lists

If this returns JSON, the connection works and the issue is in the config file. If it fails:

Permission Denied (403)

Your API key doesn't have the required scope.

Check: Go to Settings > API Keys on your Toto dashboard and verify the key's scope.

Fix: Create a new key with read,write scope. Revoke the old one.

Reconciliation Issues

"No Matches Found"

Tasks need metadata for accurate matching. Without metadata, matching falls back to title-only keyword overlap, which rarely produces results.

Diagnose: Run /toto-lint to check metadata coverage. If coverage is below 70%, most tasks can't be reconciled.

Fix:

/toto-enrich --all

This generates metadata for bare tasks. Review the before/after preview and approve.

Too Many False Positives

Keywords are too generic. Terms like fix, update, code, service, function appear in almost every commit and match unrelated tasks.

Diagnose: Run /toto-lint -- it flags generic keywords:

WARNING:
  ~ 2 items have generic keywords: "code", "system"

Fix: Edit the task metadata with more specific keywords. Library names, API names, data structures, and protocol terms work best. See Task Metadata for rules.

Reconciliation Not Firing Automatically

The post-commit hook only fires on git commit commands run through Claude Code's Bash tool.

Not triggered by:

Fix: For commits made outside Claude Code, run manually:

/toto-reconcile --depth 50

Or rely on the session-start hook to catch them when you open a new Claude Code session.

Verify hooks are configured: Check that ~/.claude/settings.json contains the PostToolUse hook. See Claude Code Integration for the full config.

Sync Issues

Client Falling Behind

If a client's stored sequence number falls behind (e.g., after server changes), the delta sync may return more data than expected.

Fix: If the sync response includes resync_required: true, the client should discard local state and do a full sync:

curl -s "https://toto.up.railway.app/api/sync/changes?since=0" \
  -H "Authorization: Bearer your_token"

Unexpected Conflict Resolution

Toto uses Last-Writer-Wins (LWW) based on timestamps. If two devices edit the same item, the later timestamp wins. This can be surprising when a background sync pushes an older change that overwrites a newer edit.

Common scenario: You edit a task on your phone while your laptop's background sync pushes stale data. The laptop's edit has an older timestamp, so the phone's edit should win -- unless the laptop's clock is ahead.

Fix: Toto clamps timestamps more than 5 minutes in the future to prevent clock skew from unfairly winning conflicts. If you see clock_skew_detected: true in push responses, check your device clock.

UI Issues

VIM Mode Interfering with Text Input

If keystrokes are being captured by VIM mode when you're trying to type in a text field, press Escape first to ensure you're in Normal mode, then click the input field.

VIM mode should automatically detect when an input field is focused and pass keystrokes through. If it doesn't:

Fix: Disable VIM mode:

localStorage.setItem('toto-vim-mode', 'off');

Reload the page. See VIM Mode for the full reference.

Animations Too Heavy on Older Hardware

TotoFX adapts to device capabilities, but very old hardware may still struggle with particle systems and fluid simulation.

Fix: Open the FX sidebar (FX button in the header) and:

  1. Reduce the Intensity slider to lower particle counts
  2. Reduce the Speed slider to lower physics simulation rate
  3. Switch to simpler animation variants (fade instead of confetti)

Dashboard Not Updating in Real-Time

The Toto dashboard uses Server-Sent Events (SSE) for live sync. If updates aren't landing:

  1. Open browser DevTools → Network → filter by EventSource. Look for the /api/events connection — it should stay open with a 200 status.
  2. If it fails or keeps reconnecting: check whether a corporate firewall or VPN is blocking long-lived HTTP connections to toto.tech. SSE is plain HTTPS but some proxies aggressively buffer or close idle streams.
  3. If /api/events is closed entirely: ensure third-party cookies / cross-origin requests aren't blocked for toto.tech.
  4. Reload the page once. The client retries SSE automatically with backoff; a fresh page picks up cleanly.

If the issue persists, reach out — include the EventSource request status from DevTools.

Common Questions

Can I use Toto without Claude Code?

Yes. The web dashboard and REST API work independently. Claude Code integration is the recommended workflow, but you can use the API from any HTTP client, build custom integrations, or just use the web UI directly.

Can I use Toto with Cursor, Copilot, or other AI tools?

Yes. Toto is API-first. Any tool that can make HTTP requests can interact with the API. The slash commands are specific to Claude Code, but the underlying API calls are standard REST -- you can adapt them for any tool.

How do I migrate from Todoist / Linear / Asana?

There's no built-in importer. The batch API makes scripting a migration straightforward:

# Export from your old tool (format varies)
# Then batch-import:
curl -s -X POST "https://toto.up.railway.app/api/lists/LIST_ID/items/batch" \
  -H "Authorization: Bearer toto_your_token" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"task": "Item 1"}, {"task": "Item 2"}, ...]}'

Up to 50 items per batch request.

Is there a mobile app?

Native iOS and macOS apps (SwiftUI + WidgetKit) are on the roadmap as the first post-launch surface. Today, the web dashboard is PWA-capable and works well in mobile browsers — install it from the share sheet for a near-native experience.

How do I print labels?

Toto has an optional DYMO LabelWriter 450 integration — the print engine renders labels with Pillow and sends them to CUPS. Items can be flagged as "printed" in the UI. This requires the desktop agent running on a machine with the printer connected. Label printing is one peripheral feature, not the product — most users never touch it.

What's the maximum number of items / lists?

There's no hard limit. The API paginates at 200 items per request. SQLite handles thousands of items without issue. PostgreSQL handles much more. In practice, personal use rarely exceeds a few hundred active items across a dozen lists.

Still Stuck?

  1. Test the API directly with curl to isolate the issue
  2. Check ~/.claude/skills/toto-config.json for correct URL and token
  3. Run /toto-lint for board health diagnostics
  4. Check server logs for errors (python main.py outputs to stdout)

Further Reading