Omnispindle

A todo system that went wonderfully, intentionally wrong.

Omnispindle is the coordination spine of the Madness Interactive ecosystem — a Python FastMCP server with 38 tools that lets AI agents manage tasks, capture knowledge, coordinate sessions, track epic goals (quests), and navigate the whole workshop from a single, standardized interface. PyPI packaged. Auth0 integrated. Runs anywhere a MCP config lives.

It started as "let's do todos properly." It became the central nervous system for a multi-project AI-assisted development lab. Both of these things are fine.

---

What it actually does

Todo management — the boring part that enables everything else. Agents can create, query, update, complete, and audit tasks across any project in the ecosystem with full metadata, priority, target agent tracking, and change detection.

Knowledge capture — lessons learned get stored with language, topic, and tag metadata. Searchable by regex, text, or vector embedding. The institutional memory doesn't evaporate when the conversation ends.

Session tracking — AI work sessions in Inventorium can be forked, spawned, linked to todos, and traced through a full genealogy tree. Every thread of work has a parent and a lineage.

Semantic search — find_relevant uses vector embeddings to surface todos and lessons by meaning, not just keywords. get_context_bundle gives an agent the full project picture in one call.

---

Installation

pip install omnispindle

CLI commands available after install:
- omnispindle-stdio — MCP stdio server for Claude Desktop
- omnispindle / omnispindle-server — HTTP web server for authenticated endpoints

Claude Desktop (zero config)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "omnispindle": {
      "command": "omnispindle-stdio",
      "env": {
        "OMNISPINDLE_MODE": "api",
        "OMNISPINDLE_TOOL_LOADOUT": "basic",
        "MCP_USER_EMAIL": "you@example.com"
      }
    }
  }
}

First tool call opens your browser for Auth0 login. Token saves locally. That's it.

Development

git clone https://github.com/DanEdens/Omnispindle.git
cd Omnispindle
pip install -r requirements.txt
python -m src.Omnispindle.stdio_server

---

Tools

Full loadout is 38 tools across 7 categories. Control what's available — and your agent's token budget — with OMNISPINDLE_TOOL_LOADOUT.

Todo Management (9 tools)

| Tool | What it does | |------|-------------| | add_todo | Create a task with project, priority, target agent, notes, and metadata | | query_todos | MongoDB-style filter queries with projection, limit, offset, since change detection, and graph_root for dependency subgraph traversal | | update_todo | Patch any fields; metadata is deep-merged. Supports $push/$pull on array fields (e.g. metadata.blockers) for dependency linking | | delete_todo | Remove a task | | get_todo | Fetch a single task by ID | | complete_todo | Stage for review with optional comment; writes to audit log. Sets status to review, not completed | | list_todos_by_status | Filter by status: pending initial in_progress blocked review completed | | search_todos | Tokenized multi-word fuzzy text search | | list_project_todos | Recent tasks for a specific project |

Knowledge / Lessons (7 tools)

| Tool | What it does | |------|-------------| | add_lesson | Capture a lesson with language, topic, and tags | | get_lesson | Fetch by ID | | update_lesson | Patch lesson content or metadata | | delete_lesson | Remove | | search_lessons | Text search across lesson fields | | grep_lessons | Regex pattern search | | list_lessons | Browse all lessons, with brief mode for summaries |

Inventorium Sessions (8 tools)

| Tool | What it does | |------|-------------| | inventorium_sessions_list | List sessions, optionally filtered by project | | inventorium_sessions_get | Fetch a session by ID | | inventorium_sessions_create | Start a new AI work session | | inventorium_sessions_spawn | Spawn a child session from a parent, linked to a todo | | inventorium_sessions_fork | Fork a session with optional message inheritance | | inventorium_sessions_genealogy | Full ancestor/descendant trace for a session | | inventorium_sessions_tree | Visual session tree for a project | | inventorium_todos_link_session | Link a todo to a session |

Quest System (5 tools)

| Tool | What it does | |------|-------------| | create_quest | Create an epic goal container (Quest → Chains → Todos). Use instead of add_todo for multi-step objectives | | check_quest | Progress report: % complete, per-chain status, next actions, blockers. Agent orientation tool | | list_quests | List quests filtered by status/project | | link_quest | Add an existing todo to a quest chain retroactively (creates chain on demand) | | update_quest | Update quest fields: name, description, status, success_criteria, metadata |

Context & Search (4 tools)

| Tool | What it does | |------|-------------| | get_context_bundle | One call: recent todos, lessons, session state, project stats for an agent's working context | | find_relevant | Semantic similarity search across todos and lessons. Returns honest empty when nothing clears the relevance threshold — no regex fallback noise | | preflight_rag | Pre-task lessons check: call before starting work, classifies past solutions vs pitfalls | | write_agent_journal / read_agent_journal | Persistent agent journal — leave notes readable by other agents for cross-agent coordination |

System / Admin (5 tools)

| Tool | What it does | |------|-------------| | query_todo_logs | Audit log queries: filter by type, project, date range | | list_projects | Enumerate known projects from filesystem | | explain / add_explanation | Topic explanation system: persistent knowledge cards | | point_out_obvious | Logs an observation with configurable sarcasm. Useful for marking known issues during automated runs. |

Custom Code (1 tool)

| Tool | What it does | |------|-------------| | bring_your_own | Inject a Python, JavaScript, or shell function as a live MCP tool at runtime |

---

Tool Loadouts

Set OMNISPINDLE_TOOL_LOADOUT to control what's registered:

| Loadout | Tools | Use case |
|---------|-------|----------|
| full | 38 | Everything |
| basic | 15 | Core todo CRUD + context + quest system |
| minimal | 4 | Add, query, get, mark complete |
| lessons | 8 | Knowledge management only |
| admin | 16 | Admin tasks + session management |
| write_only | 6 | Create/update/delete only |
| read_only | 16 | Query/get only |
| lightweight | 13 | Token-optimized core |
| agent_preflight | 6 | Session startup: context bundle, RAG check, todo ops |
| refine | 13 | Todo enrichment: audit + fill missing metadata |

---

Operation Modes

Set via OMNISPINDLE_MODE:

- api — HTTP calls to madnessinteractive.cc/api. No local database needed. Best for cloud-native or multi-user setups.
- hybrid (default) — API-first with MongoDB fallback. Reliable when the network isn't.
- local — Direct MongoDB connections only. Good for offline development.
- auto — Benchmarks both and picks the faster one.

---

Authentication

Zero-config device flow: On first tool call, a browser window opens for Auth0 login. Token is saved locally. All subsequent calls are authenticated without any configuration.

Manual token setup (optional):

python -m src.Omnispindle.token_exchange

Environment variables:
- MADNESS_AUTH_TOKEN or AUTH0_TOKEN — JWT from Auth0 device flow
- MCP_USER_EMAIL — required for per-user data isolation
- MADNESS_API_URL — override API base (default: https://madnessinteractive.cc/api)

All data is scoped per user at the database level. Your todos stay yours.

---

Configuration

…