Matoi

A CLI platform where AI agents work as a complete startup team: from market validation to product launch -- strategists, researchers, marketers, engineers argue on substance and produce artifacts.

Matoi -- a Japanese firefighter's standard, around which the team rallies.

Why Matoi

Quick Start

pipx install matoi
matoi

On first launch, Matoi asks for an Anthropic API key, scans the project, builds a code graph, and shows you the main menu.

How It Works

$ matoi

███╗   ███╗ █████╗ ████████╗ ██████╗ ██╗
████╗ ████║██╔══██╗╚══██╔══╝██╔═══██╗██║
██╔████╔██║███████║   ██║   ██║   ██║██║
██║╚██╔╝██║██╔══██║   ██║   ██║   ██║██║
██║ ╚═╝ ██║██║  ██║   ██║   ╚██████╔╝██║
╚═╝     ╚═╝╚═╝  ╚═╝   ╚═╝    ╚═════╝ ╚═╝

  Your startup team in the terminal.
  v0.3.8

  Project: my-project
  Files: 42 | Dirs: 8
  Languages: Python (28), JavaScript (6)
  Git: 156 commits

  Code graph: 210 nodes, 1317 edges
  3D city built.

? What would you like to do?
  > Start working -- select PM and team
    View code graph -- open in browser
    View 3D city -- open CodeCharta
    Browse agents -- see all 17 agents
    Session history -- past sessions and costs
    Quit

You type tasks -- the agent team works behind a spinner (no live code streaming). Only descriptions and "Created: filename" appear in the console. Tab autocompletes commands and @agents with descriptions. Alt+Enter for multiline.

On repeated launch in the same project, Matoi offers to continue the previous session or start a new one.

Two Pipeline Modes

Advisory Mode (default)

1. Selective Activation   -- Haiku picks relevant agents for this task
2. PM Brief               -- PM formulates goal, constraints, deliverables
3. Expert Pass            -- each agent gives opinion (streaming + markdown)
4. Conflict Detection     -- Haiku scans for disagreements (severity >= 0.5)
5. Debate                 -- structured rounds if conflicts found, skipped if not
6. Synthesis              -- PM decides, incorporating debate results

Execution Mode (/execute)

/execute Build authentication module

PM decomposes -> 4 subtasks:
  [DONE]    Backend Engineer: design auth schema
  [DONE]    Security Reviewer: threat model
  [BLOCKED] Frontend Engineer: login UI (waiting on schema)
  [DONE]    QA Strategist: test plan

Context Compaction

Session: 15 tasks, 50+ agent responses
  -> context at 85% (170K tokens)
  -> old messages compressed to summary (500 tokens)
  -> last 6 messages kept as-is
  -> session continues without degradation

17 Agents

PM -- 4 management styles:

Executors -- implementation:

Thinkers -- research and strategy:

Critics -- review and quality:

Each agent is a .md file with YAML frontmatter: role, debate style, model policy, strengths, weaknesses, activation rules.

CLI Commands

matoi                          # interactive session
matoi run "task"               # one-shot pipeline
matoi cost                     # cost breakdown by sessions and models
matoi history                  # browse past sessions and artifacts

matoi roster list              # agent table
matoi roster show startup-pm   # card with pixel-art avatar

matoi team create              # assemble a team
matoi team show / list         # view teams

matoi memory show              # MemPalace status
matoi memory search "query"    # semantic memory search

matoi viz graph                # dependency graph in browser
matoi viz city                 # 3D code city (CodeCharta)

matoi task plan "task" -t demo # dry run

Session Commands

/help      -- all commands
/team      -- current team
/agents    -- all 17 agents
/cost      -- session cost breakdown
/history   -- tasks in this session
/standup   -- generate session summary
/execute   -- PM decomposes task, agents execute subtasks
/commit    -- review diff -> debate -> commit -> update graph
/key       -- change API key
exit       -- exit session (also: quit, q, Ctrl+D)

On session exit, a summary is printed: files created, tasks completed, debates held, and a cost table with model column. The summary is also saved as an artifact and indexed in MemPalace.

Cost Routing

Typical task with 3 agents, no debate: $0.30-0.80.

Integrations

Project Structure

~/my-project/
  .matoi/
    config.json          -- PM + team for this project
    artifacts/           -- standup reports, debate transcripts
    memory/
      palace/            -- MemPalace per-project (semantic search)
      knowledge_graph.sqlite3  -- per-project knowledge graph
  index.html             -- files created by agents (in project root)

~/.matoi/
  config.json            -- API key (global, shared across projects)
  history                -- input history (shared)

src/matoi/
  cli/           -- Typer + Rich + prompt_toolkit + Questionary
  core/          -- Pydantic models (Agent, Team, Task, Cost, Config)
  orchestrator/  -- Pipeline, Dispatch, Debate, Conflict, Compaction
  agents/        -- Registry, Activation, Runtime
  storage/       -- MemPalace wrapper, Artifacts, Costs
  gateway/       -- Anthropic SDK, ModelRouter, Pricing

agents/          -- 17 agent .md files (YAML frontmatter)
assets/avatars/  -- pixel-art PNG avatars

Requirements

• Python 3.11+
• Anthropic API key
• Optional: CodeCharta (Java 17+ for 3D visualization)