Eureka

Your personal board of advisors — a local-first, role-based agent system for OpenCode.

Eureka gives you a team of AI specialists that live on your machine. One orchestrator (Ultima) routes your request to the right specialist — researcher, teacher, developer, designer, market strategist, finance, legal, and more — then validates and synthesizes the result. No embeddings, no external state, no cloud vendor lock-in for memory.

Why Eureka

• Local-first: state lives in SQLite + Markdown on disk, not a vector database.
• Specialist model: 13 roles with distinct personalities, permissions, and contracts.
• Sequential execution: subagents spawn one at a time; no chaotic parallel loops.
• Contract-validated output: every subagent returns structured data validated against YAML schemas.
• Privacy by default: MCP servers are disabled until you explicitly approve them.

Architecture

User
  |
  v
Ultima (orchestrator / gatekeeper)
  |
  +-- Minerva  (research, web, documents)
  +-- Chiron   (teaching, explanation)
  +-- Specialist
        Atlas (architecture)     Metis (product)
        Vulcan (development)     Hermes (market)
        Aura  (design)           Juno  (BD)
        Fama  (growth)           Plutus (finance)
        Dike  (legal)            Philia (community)
  |
  v
Validation -> Synthesis -> User

Quick Start

# Clone
git clone https://github.com/oxelmour/eureka.git
cd eureka

# Install with uv (recommended)
uv sync --extra dev

# Run tests
uv run pytest

OpenCode Setup

1. Restart OpenCode in the repo directory so it discovers .opencode/agents/ and .opencode/skills/.
2. The default primary agent is Ultima. Ask anything; Ultima will decide whether to answer directly, research with Minerva, teach with Chiron, or invite a specialist.

Firecrawl (Optional)

Firecrawl gives Minerva high-quality web search, scraping, and crawling. It is disabled by default.

# Install globally (requires Node.js)
npm install -g firecrawl-mcp

# Create an API key at https://firecrawl.dev/app/api-keys
# Then set it as a user-level env var (Windows PowerShell)
[Environment]::SetEnvironmentVariable("FIRECRAWL_API_KEY", "fc-...", "User")

Then enable it in opencode.json:

"mcp": {
  "firecrawl": {
    "enabled": true
  }
}

Restart OpenCode after changing the config.

Roles

Role	Domain	Spawns When
Ultima	Orchestration	Always (primary)
Minerva	Research	You need facts, sources, or market intel
Chiron	Teaching	You want to understand, not just know
Atlas	Architecture	You design systems, databases, APIs
Vulcan	Development	You write, debug, or review code
Aura	Design	You need UX, accessibility, or visual direction
Metis	Product	You prioritize features or define roadmaps
Hermes	Market	You analyze competitors or pricing
Juno	Business Dev	You structure partnerships or deals
Fama	Growth	You need distribution, SEO, or viral mechanics
Plutus	Finance/Ops	You model unit economics or budgets
Dike	Legal	You review compliance or contracts
Philia	Community	You build community health or engagement

Project Structure

.
├── .opencode/
│   ├── agents/           # OpenCode runtime definitions (13 agents)
│   └── skills/           # Local skill library (deep-research)
├── config/
│   ├── roles.yaml        # Role registry & spawning policy
│   ├── limits.yaml       # Approval rules & safety thresholds
│   └── mcp-candidates.yaml  # Audited MCP catalog (disabled by default)
├── contracts/            # YAML schemas for subagent outputs
│   ├── default.yaml
│   ├── research.yaml
│   ├── teaching.yaml
│   └── specialist.yaml
├── memory/
│   ├── state.py          # SQLite session & decision store
│   └── semantic/knowledge.md  # Human-curated knowledge base
├── pipeline/
│   ├── routing.py        # Keyword-based task routing logic
│   ├── validator.py      # Contract validation engine
│   ├── aggregator.py     # Sequential result synthesis
│   └── loaders.py        # Role & contract file parser
├── roles/
│   ├── _core/            # Ultima, Minerva, Chiron
│   └── _specialist/      # 10 startup strategist role files
├── tests/                # pytest suite (11 tests)
├── skills/               # Skill registry & policy
├── tools/                # Shared file/search utilities
├── roles.md              # Original role manifesto (reference)
├── opencode.json         # OpenCode runtime configuration
└── pyproject.toml        # Python project definition

Safety Model

• Least privilege: Every specialist runs with restricted file/system access.
• Approval-gated actions: Deletion, overwrites, public posts, pushes, and financial commitments require your explicit confirmation.
• No recursive spawning: Specialists cannot spawn other specialists; deep tasks return a handoff request to Ultima.
• MCP audit trail: Every MCP server is vetted in config/mcp-candidates.yaml and must be enabled manually.

Development

# Run tests
uv run pytest

# Compile check
uv run python -m compileall -q memory pipeline tools tests

# Lock check
uv lock --check

Adding a New Role

1. Copy a template from roles/_template.md (or copy any existing role file).
2. Update frontmatter: name, domain, layer.
3. Write the prompt in English.
4. Register it in config/roles.yaml under the right layer.
5. Create a runtime file in .opencode/agents/<name>.md pointing to the role file.
6. Run tests to verify consistency.

Adding a Skill

1. Create .opencode/skills/<skill-name>/SKILL.md.
2. Add an entry to skills/registry.json with source and status.
3. Reference it in the role's skills.approved list if it should auto-load.

Contributing

This is primarily a personal research project. Issues and PRs are welcome, but the architecture may evolve quickly.

License

MIT — do whatever you want, but don't blame me if your agents are too loud at 3 AM.

---

Built with a lot of coffee and an unusually high tolerance for YAML. "Eureka!" is what you say when Minerva finally finds the answer.