What Is Toto

Toto is the interaction layer for the human-agent world model.

People and agents see the same state, act on it in real time, and the world evolves through their joint actions. Task management, agent observability and shared world model are all the same thing — they are all answers to the same question: what is happening right now between the people and the agents doing this work?

Read the Vision for the full thesis.

The Problem

Agents generate content at a rate that far outpaces what a person can consume. The world model — files, logs, code changes, status updates, decisions, metadata — grows fast and quickly becomes useful only for the agent.

There is an inverse relationship between the size of a world model and its human accessibility.

You're running five agents in parallel. Each one generates code changes, status updates, decisions. The world model grows. The agent knows everything. You see nothing. You alt-tab to Linear to update a ticket — fifteen seconds of friction, repeated forty times a day. Or you don't, and the board rots.

There's a second problem: if you use Obsidian for knowledge management, you've noticed it's excellent for notes, docs, and decision records — but terrible for task tracking. Obsidian tasks are static checkboxes buried in markdown files. No real-time updates, no animations, no API, no way for an AI agent to create or complete tasks. You end up with knowledge in Obsidian and tasks in some other tool that doesn't talk to either your editor or your vault.

Toto fixes both problems. Task management becomes a side effect of the work itself — a state transition in the shared world model.

How It Works

Toto is the shared persistent state where both agents and people interact through their actions.

When you check off a task, that's an action on the world model. When an agent marks a subtask done, same thing. When either side adds context, reprioritizes, or surfaces a decision — those are state transitions in the world model. Both sides see the same state. Both sides act on it.

Semantic Reconciliation

After a git commit, Toto connects disparate world model data — Obsidian documentation, git commits, agent logs, file changes — to human-defined tasks and presents it in human-first documents. Multiple signals are used: file path overlap, keyword matching, component alignment, scope validation. Confident matches are presented for quick confirmation. The world model stays accessible as it grows.

Enrichment

Enrichment adds rich, agent-native metadata to human work — component tags, file paths, keywords, intent statements — empowering the world model from the human side. Every task carries structured metadata that powers reconciliation and makes the world model machine-readable without sacrificing human readability.

Shared Task Management

Agents and people create, track and complete tasks on the same board. An agent starts a subtask and it glows. It finishes and it animates. The human sees this happen live. This is not a dashboard for monitoring agents — it's a shared workspace where both sides act.

Always Visible, Always Synced

Phone. Web. CLI. MCP server. Desktop tray. The world model lives everywhere you do — not buried in an app you have to remember to open. SSE provides real-time push. Delta sync handles offline-first clients. Change a task's status from the terminal and watch the card animate on your second monitor. Native macOS and iOS apps with WidgetKit are on the roadmap.

Physics-Based Interaction

TotoFX is a custom physics-based animation engine — composable effect layers, fluid simulation, particle systems, user-tunable parameters. Zero external dependencies. This is the haptic layer of the interaction — when you watch a task animate on completion, your brain registers the accomplishment differently than clicking a checkbox. Beautiful when it should be, invisible when it should be, always there.

VIM Mode

Modal keyboard navigation on the web dashboard. j/k to move through items, Tab/Shift-Tab between lists, d to mark done, s for in-progress, x to delete. Count prefixes work (3j moves 3 items down). i enters insert mode for adding items, Esc returns to normal mode.

Agent Integration

Toto is agent-native. The same API surface serves humans (web, CLI, desktop) and agents (MCP, REST).

MCP Server

Published on PyPI. Any MCP-compatible client — Claude Code, Claude.ai, Cursor — can create lists, add tasks, update status, and read the shared state. The MCP server is API-backed with no direct database access.

Claude Code Slash Commands

12 slash commands ship with Toto, installed via curl -fsSL https://toto.tech/install | bash. /toto-plan breaks a feature description into actionable subtasks with metadata. /toto-start and /toto-done control status with real-time visual feedback. /toto-reconcile matches git commits to tasks. /toto-search (alias /ts) finds items across every list. Every slash command works via the REST API.

REST API

Full JSON API with scoped authentication (read/write/admin). Device tokens and API keys. If your tool can run curl, it can interact with the world model.

Security

Authentication: Scoped API keys (read/write/admin) with SHA-256 hashed device tokens. Google and Apple OAuth. HMAC-signed session cookies. Anonymous sessions with upgrade path.

CSRF Protection: Double-submit cookie pattern on all state-changing web requests. API routes use Bearer token auth.

Rate Limiting: Per-key, per-IP, and per-account limits via slowapi. Auth endpoint lockout after repeated failures.

Data Isolation: All queries scoped to the authenticated user. SSE events filtered by user scope. API keys only access their owner's data.

Transport Security: HSTS, CSP, X-Frame-Options, X-Content-Type-Options. All production traffic over TLS.

See It Live

/demos — Cost-aware routing, lifecycle, Obsidian integration, enrichment, Claude Code, reconciliation. Each demo runs in real time.
/playground — Tune every animation, dotgrid effect, and theme on philosophy quote test cards.
/api-docs — Full REST API surface.
/games/clicker — A small clicker game built on the animation engine.

Getting Started

The fastest way to try Toto is to visit the homepage — anonymous sessions get a real list, real animations, and 30 days of cross-tab sync without an account. Signing up promotes that session into a permanent account without losing data.

For agent integration, install the slash commands and configure your API connection in under 5 minutes:

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

Then in Claude Code:

/toto-setup
/toto-plan "My first feature"

See the Quickstart for the full setup guide.