🔮 Thoth 🔮

Recording knowledge, building truth

Memory Control Plane for human + AI work. Turn ideas into shipped features with Claude Code or Codex as your development team. Build products and infrastructure with automated workflows, validation, and memory that compounds over time.

Bring your own stack. Run Thoth from any project root, or use projects/ as the canonical workspace layout (repos/ remains a compatibility alias).

5-Minute Start

# Install and verify CLI
git clone https://github.com/Vitalsine85/thoth.git ~/thoth
cd ~/thoth
npm link
thoth doctor

# Initialize from any project
cd /path/to/your-project
thoth init
thoth memory doctor
thoth --codex

Legacy workspace users: run thoth workspace bootstrap from your Thoth home. Next: Run /thoth:explore in Claude Code, or jump to Quick Start Guide

Choose Your Path

Find your journey in 30 seconds:

| I am a... | I want to... | Start here | |-----------|--------------|------------| | Product Manager / Growth | Turn ideas into features without coding | Non-Technical Guide | | Frontend Developer | Build React/TypeScript features | Frontend Guide | | Smart Contract Developer | Work with Solidity/Foundry contracts | Contract Guide | | Backend Developer | Build Rust/GraphQL services | Backend Guide | | DevOps / Infrastructure | Deploy and manage services | DevOps Guide | | Just Exploring | See it work in 5 minutes | Quick Start |

How It Works

Think of it like a development team where you're the manager and Claude is your lead developer:

• You describe what you want - The system asks clarifying questions, researches the codebase, and creates an execution plan
• AI handles the implementation - Specialized sub-agents write code, tests, and documentation while following protocol rules
• Quality gates enforce standards - Every change gets reviewed by a separate agent before completion
• Knowledge accumulates - Each project makes the system smarter for everyone

Thoth orchestrates work across your repositories with domain-aware validation, so you cannot accidentally break critical paths.

Memory Hierarchy

Thoth is an agnostic memory control plane organized as:

• Personal: private operator memory and preferences
• Project: repository and initiative-specific working memory
• System: shared rules, workflows, and operational standards
• Remote (optional): external high-level memory source via adapter/plugin

Intuition is one example of a Remote adapter. Thoth does not require Intuition.

Key Features

• 62 Specialized Commands - /thoth:start-ticket, /thoth:create-plan, /thoth:review-pr, and more
• AI-Powered Development - From idea to PR with planning, implementation, testing, and review agents
• Multi-Repo Coordination - Work across frontend, contracts, and backend seamlessly
• Domain Validation - Configurable correctness checking for critical code paths
• Enforced Gate Policies - CI policy verdict (policy-verdict) blocks merges when required checks fail
• Integration Ecosystem - Linear (tickets), GitHub (PRs), Obsidian (notes), Slack (notifications)
• Knowledge Accumulation - System learns from every project and shares patterns across the team
• Batch Commits - Clean, semantic commit history generated automatically
• Cross-Stack Intelligence - Frontend patterns inform contract work and vice versa

Experimental:

• 🧪 Autonomous Mode - Full autonomous development loops (see Autonomous Mode)
• 🧪 Local Models - GPU-based execution with Ollama (see Local Models)
• 🧪 Swarm Teams - Multi-agent collaboration (see Swarm Patterns)
• 🧪 Protocol Agents - Experimental MCP workflow (not part of v0.1 release scope)

What You Can Build

Example 1: Add a Feature (30 minutes)

Goal: Add social sharing to item cards

You: "Add a share button to item cards that posts to X/Twitter"

System:
1. Researches existing patterns in the codebase
2. Creates implementation plan
3. Implements component with proper styling
4. Writes tests
5. Creates PR with description
6. Updates Linear ticket status

Result: Production-ready feature with tests, docs, and review approval

Example 2: Fix a Cross-Repo Bug (1 hour)

Goal: Fix a data inconsistency across services

You: "Users report incorrect values in the dashboard"

System:
1. Searches vault history and related issues
2. Analyzes data flow across backend, API, and frontend
3. Identifies calculation mismatch
4. Proposes fix with domain expert validation
5. Implements fix across all layers
6. Generates regression tests
7. Creates hotfix PR with detailed explanation

Result: Bug fixed with full test coverage and domain validation

Repository Map

Thoth can run in either model:

| Model | Default | |-------|---------| | Project-local (thoth init in each repo) | Yes | | Shared workspace (projects/; repos/ compat alias) | Optional via thoth workspace bootstrap |

Project-local usage keeps each repo independent while still using shared Thoth automation.

Example map:

| Repository | Stack | Brain File | Purpose | |------------|-------|------------|---------| | <project-root> | React, TypeScript | brains/frontend.md | Web application | | <contracts-root> | Solidity, Foundry | brains/contracts.md | Smart contracts | | <backend-root> | Rust/Node/Python | brains/backend.md | Backend services | | <sdk-root> | TypeScript | -- | Client libraries | | <other-project-roots> | Any | -- | Additional repositories |

Brain Files: Specialized knowledge bases that load automatically based on your task. They contain patterns, conventions, and domain expertise for each area.

Integrations

Connect to your existing workflow:

| Integration | What It Does | Setup Guide | |-------------|--------------|-------------| | Linear | Automatic ticket creation, status updates, linking | Linear Setup | | GitHub | PR automation, code review, CI/CD | GitHub Setup | | Obsidian | Progress tracking, knowledge base, daily notes | Obsidian Setup | | Blockchain RPC | Protocol queries, transaction monitoring | RPC Setup | | Slack | Notifications, alerts, status updates | Slack Setup | | X/Twitter | Social features, posting, mentions | X Setup |

Network Configuration: Set your RPC endpoints and contract addresses in .env (see .env.example).

Documentation Map

Getting Started

• Installation - Setup and dependencies
• Quick Start - First project in 5 minutes
• First Project - End-to-end walkthrough
• Troubleshooting - Common issues
• Migration Command Map - Old workspace commands to CLI-first equivalents

Guides by Role

• Non-Technical User - Product managers, designers, growth
• Frontend Developer - React, TypeScript, UI components
• Smart Contract Developer - Solidity, Foundry, testing
• Backend Developer - Rust, GraphQL, indexing
• DevOps Engineer - Deployment, monitoring, infrastructure
• Cross-Repo Memory Workflow - Shared canonical vault for multi-repo initiatives
• Cross-Repo Research Workflow - Repeatable research-to-Linear handoff for multi-repo initiatives

Reference

• Commands - All 62 slash commands
• Skills - Specialized agent capabilities
• Sub-Agents - Agent types and routing
• MCP Servers - Model Context Protocol integrations
• Brain Files - Knowledge base structure
• Workflow Examples - Real-world scenarios

Advanced

• Local Models - GPU-based execution with Ollama
• Autonomous Mode - Full autonomous loops
• Custom Skills - Build your own commands
• Performance Tuning - Optimization strategies
• Swarm Teams - Multi-agent collaboration
• Contributing - Improve Thoth

What's Inside

thoth/
├── .claude/                    # Claude Code configuration
│   ├── commands/              # 62 slash commands
│   ├── subagents/             # Specialized AI agents
│   ├── rules/                 # Auto-loaded behavior rules
│   └── hooks/                 # Git hooks and automation
│
├── brains/                     # AI knowledge bases
│   ├── frontend.md            # React Router 7 patterns
│   ├── contracts.md           # Solidity conventions
│   ├── backend.md             # Rust/GraphQL patterns
│   ├── domain-context.md      # Your domain knowledge
│   ├── brand-identity.md      # Brand voice, UX principles
│   └── ...                    # 15+ specialized brains
│
├── docs/                       # Human documentation
│   ├── getting-started/       # Installation, quick start
│   ├── guides/                # Role-based guides
│   ├── reference/             # Commands, APIs
│   └── advanced/              # Deep dives
│
├── obsidian-vault/            # Knowledge accumulation
│   ├── projects/              # Project planning docs
│   ├── learnings/             # Extracted patterns
│   ├── daily/                 # Session notes
│   └── agents/                # Agent development
│
├── projects/                   # Canonical shared workspace layout
├── repos/                      # Compatibility alias (symlink to projects/)
│   ├── your-frontend/         # Frontend
│   ├── your-contracts/        # Smart contracts
│   ├── your-backend/          # Backend services
│   └── ...                    # Additional repos
│
├── bin/                        # Automation scripts
│   ├── core/                  # Setup, commit automation
│   ├── workflows/             # Ticket-to-PR pipelines
│   └── integrations/          # Linear, GitHub, Slack
│
├── CLAUDE.md                   # Master brain (auto-loads)
├── CLAUDE.local.md            # Your private settings
└── README.md                   # This file

Quick Tips

• Start with /thoth:explore - Discover all available commands organized by workflow
• Check workflow examples - Real scenarios in docs/reference/workflow-examples.md
• Use mission control - Run /thoth:mission-control to see all active work across repos
• The system learns - Document findings in the vault so the team benefits
• Domain-aware validation - The system prevents breaking changes to your critical code paths
• Let Claude lead - It knows the codebase and patterns deeply

Common Workflows

Start a New Ticket

/thoth:start-ticket ENG-123
# Creates feature branch, loads context, ready to work

Create an Implementation Plan

/thoth:create-plan Add user profile avatars
# Researches codebase, creates BRIEF/ROADMAP/PLAN, suggests approach

Implement a Feature

/thoth:create-prompt Implement avatar upload component
# Writes code, tests, docs with batch commits

Review a Pull Request

/thoth:review-pr
# Comprehensive code review with protocol validation

Check Daily Progress

/thoth:mission-control
# Shows all active work, blockers, next actions

End Your Day

/thoth:end-day
# Creates checkpoint, updates vault, prepares handoff

See Commands Reference for all 62 commands.

Experimental Features

🧪 Autonomous Mode

Full autonomous development loops. The system takes a high-level goal and works independently through planning, implementation, testing, and review with periodic check-ins.

Status: Production-ready with safeguards Learn more: docs/advanced/autonomous-mode.md

🧪 Local Models

Run 30B+ parameter models locally on your GPU (18GB VRAM). Faster iteration, lower costs, full privacy. Integrates with Ollama.

Status: Experimental, requires GPU Learn more: docs/advanced/local-models.md

🧪 Swarm Teams

Multi-agent collaboration where specialized agents work in parallel on different aspects of a feature, then synthesize results.

Status: Experimental Learn more: docs/advanced/swarm-teams.md

🧪 Protocol Agents (MCP)

Direct protocol interaction via Model Context Protocol. Query on-chain data from within Claude Code.

Status: Coming soon Preview: docs/experimental/protocol-agents.md

🧪 Visual Dashboard

Web-based project tracking, metrics, and system health monitoring.

Status: Work in progress Roadmap: obsidian-vault/projects/dev-template/dashboard-v2/

Support

• FAQ: docs/getting-started/faq.md
• Troubleshooting: docs/getting-started/troubleshooting.md
• GitHub Issues: github.com/Vitalsine85/thoth/issues
• Discord: discord.gg/your-community
• Documentation: See docs/ directory

Architecture Highlights

Delegation-First Design

Main context handles planning and coordination only. All implementation, research, and review work delegates to specialized sub-agents. This preserves context and enforces quality gates.

Domain Safety Rules

Automatic validation for domain-critical code:

• Configurable invariant checks via {DOMAIN_INVARIANT} placeholders
• Event emission for downstream consumers
• Access control on privileged operations
• Edge case handling via review gates

Knowledge Accumulation

Every project creates artifacts that make future work faster:

• Planning docs capture architectural decisions
• Implementation patterns get extracted to the vault
• Bug investigations document root causes
• Cross-repo learnings benefit all repositories

See Architecture Overview for deep dive.

Staying Up to Date

Thoth ships with a template-update subsystem for core files. To pull in upstream core improvements:

# Add Thoth as an upstream remote (one-time)
git remote add thoth https://github.com/Vitalsine85/thoth.git

# When updates are available
git fetch thoth
git merge thoth/main
# Resolve conflicts in your customized files (brains/, CLAUDE.md, etc.)

Conflicts will occur in files you've customized — that's expected and correct. Your project-specific brains, CLAUDE.md config, and vault content are yours; infrastructure changes (commands, subagents, hooks, scripts) merge cleanly.

Contributing

We welcome contributions. Thoth is designed to improve itself.

• Report Issues: GitHub Issues
• Suggest Features: Use /thoth:suggest-docs within Claude Code
• Improve Documentation: See Contributing Guide
• Share Patterns: Extract learnings to obsidian-vault/learnings/

License

MIT License - see LICENSE for details.

Built to make AI-native development delightful.

Originated from Intuition protocol's development workflow. Generalized as an open-source memory control plane for any team.

Ready to build? Start with Quick Start or run /thoth:explore in Claude Code.