Open Manifold

Multi-agent development system for opencode with persistent knowledge.

A Lead Dev agent walks through a task plan, a deterministic plugin state machine orchestrates a Senior/Junior/Debug loop, and all decisions are logged to a persistent Manifold/ folder that compounds knowledge across the project.

Core principle: Deterministic orchestration + scoped LLM execution + persistent knowledge = agents that learn and don't repeat mistakes.

Requirements

Open Manifold requires:

1. opencode-codebase-index plugin — Provides semantic code search for the Clerk's research phase. The Clerk uses it to find relevant code patterns and build focused prompts for worker agents.

2. Obsidian (optional but recommended) — The Manifold/ folder is structured as an Obsidian vault for browsing logs, tasks, and knowledge graph.

Installation:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "opencode-codebase-index",
    "opencode-manifold"
  ]
}

Two Ways to Install

Option A — npm package (Recommended)

1. Add "opencode-manifold" to your opencode.json plugins array:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-manifold"]
}

2. Run opencode. The plugin auto-installs and generates the global template source.
3. Run /manifold-init in the TUI to set up the project.

Option B — Local plugin files

1. Clone this repository
2. Copy src/ into your project's .opencode/plugins/ directory:

   cp -r src ~/.config/opencode/plugins/opencode-manifold/
   # OR copy into your project:
   mkdir -p .opencode/plugins
   cp -r src .opencode/plugins/opencode-manifold

3. Add to your opencode.json:

   {
     "plugin": ["/path/to/.opencode/plugins/opencode-manifold"]
   }

4. Run opencode. The plugin generates the global template source.
5. Run /manifold-init in the TUI to set up the project.

Quick Start

1. Install using one of the methods above
2. Run /manifold-init in the opencode TUI to set up agents, skills, and the Manifold directory
3. (Optional) Run /manifold-models to configure which models each sub-agent uses
4. (Optional) Run /manifold-update to clear plugin cache before updating (requires path configuration)
5. Create a plan — any format (markdown, TODO list, email, meeting notes)
6. Point the Lead Dev agent at your plan file and tell it to execute

The Lead Dev will:

• Extract tasks from your plan
• Dispatch each to the multi-agent system
• Log all decisions to Manifold/

Architecture

User → points to plan file (any format)
  │
Lead Dev
  Reads plan, extracts tasks, dispatches via dispatch_task tool
  │
  ▼
Plugin State Machine (TypeScript, zero LLM cost)
  │
  ├── Phase 1: Clerk research
  │     ├── codebase-index search (requires opencode-codebase-index plugin) + wiki lookback + graph entries
  │     ├── Composes scoped prompt
  │     └── Creates task log file
  │
  ├── Phase 2: Senior/Junior/Debug loop
  │     ├── Spawn Senior Dev → implementation
  │     ├── Spawn Junior Dev → review (first word: COMPLETE or QUESTIONS)
  │     ├── Loop up to 3×, then escalate to Debug
  │     └── Debug → one loop with Senior+Debug, then escalate to Clerk retry 
  │
  ├── Phase 3: Clerk logging
  │     ├── Appends design decisions to task log
  │     ├── Updates index.md, appends log.md, updates graph entries
  │     └── Returns to Lead Dev
  │
  └── Phase 4: Test (optional)
        ├── If test defined → run, check output
        └── If no test → complete

Agents

The sr/jr/debug loop enables cost-efficient workflows: a strong sr-dev paired with a cheaper junior for review, and a different model for debug (fresh perspective). The key is diversity between sr and debug, not raw power. Junior's role as reviewer means a smaller/cheaper model works well — the sr/jr loop catches most issues, and debug's different reasoning approach breaks deadlocks.

Customizing Agents

Agents are markdown files with opencode frontmatter for configuration (description, mode, permissions, model) and a body that becomes the agent's system prompt.

Manifold uses a three-tier template system:

Bundled (inside npm package)
  └── Never edit directly — overwritten on updates
        │
        ▼  Plugin load (one-time, only copies missing files)
~/.config/opencode/manifold/  ← Global templates
  ├── agents/   (clerk.md, senior-dev.md, ...)
  ├── skills/   (manifold-workflow/, clerk-orchestration/, ...)
  ├── manifold/ (settings.json, schema.md, ...)
  └── config/   (opencode.json)
        │
        ▼  /manifold-init (only copies missing files)
Project root
  ├── .opencode/agents/   ← Per-project (editable)
  ├── .opencode/skills/
  ├── Manifold/
  └── opencode.json

Per-project customization

Edit files directly in .opencode/agents/ or .opencode/skills/. These are never overwritten by /manifold-init — only files that don't exist yet are copied.

Global customization

Edit files in ~/.config/opencode/manifold/. All new projects initialized with /manifold-init will inherit your customized versions.

Resetting

To reset a specific agent to its default, delete just that file and run /manifold-init again:

rm .opencode/agents/senior-dev.md
# Then run /manifold-init

To reset all Manifold files, delete the directories and re-run:

rm -rf .opencode/agents/ .opencode/skills/ Manifold/
# Then run /manifold-init

Assigning models to agents

Interactive (Recommended): Run /manifold-models in the TUI. You'll be prompted to:

1. Select a sub-agent (clerk, senior-dev, junior-dev, or debug)
2. Choose from all available models in your configured providers

This updates the agent's frontmatter automatically.

Manual: Add a model field to the agent's frontmatter or your opencode.json:

{
  "agent": {
    "senior-dev": {
      "model": "anthropic/claude-sonnet-4-20250514"
    },
    "junior-dev": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

See the Example Configurations section for model pairing suggestions.

Example Configurations

Models change frequently. These examples prioritize sr/debug diversity and cost gradient.

Manifold Folder Structure

Manifold/
├── .obsidian/          # Makes it an Obsidian vault
├── index.md            # Catalog of all tasks
├── log.md              # Chronological append-only log
├── plans.json          # Plan registry
├── schema.md           # Wiki conventions
├── settings.json       # User-tunable parameters
├── state.json          # State machine persistence
├── tasks/              # Individual task logs
│   ├── share-cart-001.md
│   └── ...
└── graph/              # Document graph
    ├── src_middleware_auth_ts.md
    └── ...

Settings

Located at Manifold/settings.json:

Session Resumption

If a session crashes mid-loop:

• The Lead Dev reads the plan file
• Completed tasks are marked in index.md
• Lead Dev picks up from the first unmarked task
• The existing task log (created in Phase 1) shows partial work

No mid-loop state recovery needed — restart the task, the Clerk's research phase accounts for what was already done.

FAQ

Q: Do I need to configure agents? A: No. Run /manifold-init once per project and it sets up agent definitions, skills, and configuration from templates.

Q: Can I customize agents and skills? A: Yes. See the Customizing Agents section for the full three-tier template system.

Q: What is the Clerk's role? A: The Clerk has full project sight. It researches context (codebase-index, wiki, graph), composes scoped prompts for workers, and maintains the wiki.

Q: What happens if Debug also fails? A: The Clerk gets one retry with full failure context. If that also fails, the task escalates to you.

Q: Can I define tests for tasks? A: Yes. Add test: <command> in the task description or set testCommand in settings.json.

Q: What plugins does Open Manifold require? A: The opencode-codebase-index plugin is required for semantic code search. Install it alongside opencode-manifold.

Q: Is Obsidian required? A: No, but recommended. The Manifold/ folder is an Obsidian vault for browsing logs, tasks, and the knowledge graph. You can use any markdown viewer.

Q: Can I use Open Manifold without semantic search? A: The system is designed around the Clerk's ability to research context via semantic search. Modifying it would require significant changes to the Clerk's orchestration skill.

Plugin Updates

Opencode caches plugins to improve startup performance. When a new version of opencode-manifold is published, you may need to clear the cache to receive the update.

Using /manifold-update

1. Configure cache paths in Manifold/settings.json:

   {
     "updateCachePaths": [
       "~/.cache/opencode/packages/opencode-manifold@latest",
       "~/node_modules/opencode-manifold"
     ]
   }

2. Run /manifold-update in the TUI

3. Confirm the paths to clear

4. Restart opencode to pull the fresh version

Safety Features

The command includes built-in protections:

• Wildcards blocked: Paths with * are rejected
• System paths protected: /, /System, /Applications, home directory, etc. cannot be deleted
• Project detection: Directories containing .git + opencode.json or package.json are treated as projects and blocked
• Explicit confirmation: You must type "yes" to proceed

Platform-Specific Paths

macOS:

[
  "~/.cache/opencode/packages/opencode-manifold@latest",
  "~/node_modules/opencode-manifold"
]

Linux:

[
  "~/.cache/opencode/packages/opencode-manifold@latest"
]

Windows:

[
  "%LOCALAPPDATA%/opencode/packages/opencode-manifold@latest"
]

If your cache is stored elsewhere, add the full path to updateCachePaths. The command is intentionally conservative — it's safer to manually clear cache than to accidentally delete project files.

Uninstall

To remove Open Manifold from a project:

rm -rf .opencode/agents/ .opencode/skills/ Manifold/

Then remove the manifold-specific keys from opencode.json (agent.manifold, permission.clerk, permission.senior-dev, permission.junior-dev, permission.debug).

To remove global templates:

rm -rf ~/.config/opencode/manifold/ ~/.config/opencode/commands/manifold-init.md

To fully uninstall the plugin, also remove "opencode-manifold" from the plugin array in your global or project opencode.json.

Complete Clean Uninstall

For a full clean reinstall, use /manifold-update (see Plugin Updates) to clear caches, then:

# Remove project files
rm -rf .opencode/agents/ .opencode/skills/ Manifold/

# Remove global templates
rm -rf ~/.config/opencode/manifold/ ~/.config/opencode/commands/manifold-init.md

Then remove "opencode-manifold" from your opencode.json plugin array.

License

GPL 3+. See LICENSE file.