Imladris

Named for Imladris (Rivendell), seat of the Council of Elrond — where representatives of every free people gathered to weigh a hard decision together.

!Imladris Council

Design (source of truth)

docs/architecture/ — overview, pipeline, MCP surface, configuration reference, provider abstraction, judge, security, and deployment.

How it works (one paragraph)

The harness's native model calls the imladris MCP tool (via the /council or /council-session prompt). The server fans the prompt out to the configured panel (1–8 members) concurrently (each provider is a plain HTTPS call), collects answers (with partial-result tolerance), then runs an API-side analysis judge (consensus / contradictions / partial coverage / unique insights / blind spots). The tool returns that analysis plus all raw panel answers. The native model reads both and authors the final answer. A session call uses a local ~/.imladris/sessions/<thread_id>.json store to rebuild prior user/assistant turns for the next panel pass. An MCP server can't call back into the harness model, so the judge is API-side and the native model is always the outer author.

Install

Bootstrap uv and install the imladris console tool with a single command. You do not need a local checkout of this repository:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/FeanorsCodeSL/imladris/main/scripts/install.sh | sh

# Windows
irm https://raw.githubusercontent.com/FeanorsCodeSL/imladris/main/scripts/install.ps1 | iex

Each script installs uv if absent, resolves or installs Python 3.13, removes any previous imladris uv tool environment, reinstalls with the resolved Python interpreter, and verifies imladris --help before finishing. This puts two commands on your console PATH: imladris (the configurator TUI) and imladris-mcp (the MCP stdio server harnesses spawn). Until a PyPI release is uploaded, this git-URL install requires git on PATH; the installer checks that up front.

Use the installer as the supported install workflow, including for local source testing. Raw uv tool install . is only useful when deliberately debugging uv itself because it bypasses the installer safeguards.

Then run the configurator:

imladris

!Imladris TUI dashboard

The full-screen configurator loads the current config, shows the council roster, lets you add/edit/delete members, assign the judge role, writes ~/.imladris/config.json + ~/.imladris/.env (0600), and wires selected harnesses (Claude Code / Codex / OpenCode) with the imladris MCP entry. After that, continue in your harness and invoke /council, /council-session, or the imladris tool when you want deliberation.

Run imladris doctor to print the resolved roster, roles, and wired harnesses (no secrets). Use imladris refresh-catalog or the TUI refresh action to update the local models.dev cache; runtime deliberation only reads cache/seed data. Council sessions are local files under ~/.imladris/sessions/. Clear one or all of them with imladris clear-sessions [thread_id] or the imladris_clear_sessions MCP tool.

Repository layout

orchestrator/        the service package
  mcp_server.py      FastMCP server — tools: imladris, imladris_status, imladris_clear_sessions; council + council-session prompts; main()
  panel.py           panel fan-out orchestration (partial results + degradation)
  judge.py           API-side analysis judge
  model_catalog.py   offline-first model metadata, models.dev parser, cache helpers
  budget.py          advisory context-budget estimates
  sessions.py        local council-session store and message reconstruction
  providers/         single OpenAI-compatible chat provider kind + factory
  settings.py        JSON/YAML + env config loading/validation; roles panel/judge
  models.py          Pydantic request/response models
  interfaces.py      Protocol seams; fakes.py — deterministic test doubles
  costing.py         cost estimation; json_utils.py — tolerant judge JSON
  cli/               imladris configurator: TUI, catalog, config ops, secrets, probe, harness/
  tests/             pytest suite (respx for HTTP)
config/              imladris.example.yaml (illustrative providers, presets, pricing)
scripts/             install.sh, install.ps1, stdio smoke (Bash + PowerShell)
docs/architecture/   live architecture, configuration, security, deployment references
.github/workflows/   CI, sonar
.agents/skills/      imladris-deliberate skill

Develop

Requires Python 3.13.

python -m venv .venv
./.venv/bin/python -m pip install -r orchestrator/requirements-dev.txt

./.venv/bin/ruff check orchestrator           # lint
./.venv/bin/ruff format --check orchestrator  # style gate (CI enforces)
./.venv/bin/python -m pytest                  # tests

./.venv/bin/python -m orchestrator.mcp_server # run the MCP server over stdio
IMLADRIS_SOURCE="$(pwd)" ./scripts/install.sh # install/test from this checkout

On Windows, use the same installer path:

.\scripts\install.ps1 -Source .

Configuration

Run imladris to write ~/.imladris/config.json and ~/.imladris/.env (0600). The in-repo config/imladris.example.yaml is illustrative only. Both JSON and YAML config files are supported by extension; the TUI writes JSON. Secrets live only in env vars referenced by name (api_key_env) from the config — never in the config file, never logged, never returned by imladris_status.

Resolution: --config <path> → IMLADRIS_CONFIG → ./imladris.{json,yaml} → ~/.imladris/config.{json,yaml}.

Integration

Per-harness setup (Claude Code, Codex, OpenCode) is wired automatically by the imladris configurator. Every entry launches imladris-mcp over stdio with IMLADRIS_CONFIG pointed at ~/.imladris/config.json. For the manual config snippets, see docs/architecture/06-deployment.md.

License

MIT. See also SECURITY.md, CONTRIBUTING.md, THIRD-PARTY-NOTICES.md.

imladris