agenttrio

agenttrio runs bounded agent workflows made of three roles — a planner, a coder, and a separate read-only reviewer — against a local Ollama backend. It reports the workspace status, runs one task through the trio behind a host-enforced verification gate, and runs the workspace's configured checks. One binary serves a command-line interface and a stdio MCP server with exactly three tools.

Work is bounded by the operator config: model turns per role, coder → verification → reviewer cycles, total tool calls, and context size all have explicit budgets, and a run is only verified when the gate below passes — never on the model's say alone.

Configuration

agenttrio reads an operator-reviewed TOML file. Passing --config <file> explicitly approves loading that file; a workspace config.toml or .flow.toml is never auto-loaded. The only auto-loaded location is $XDG_CONFIG_HOME/flow/config.toml.

workspace_dir = "/absolute/path/to/workspace"

[ollama]
base_url = "http://127.0.0.1:11434"
model = "qwen2.5-coder:7b"
timeout = 120

[models]
planner = "qwen2.5-coder:7b"
coder = "qwen2.5-coder:7b"
reviewer = "qwen2.5-coder:7b"

[agent]
max_iterations = 6
max_cycles = 2
max_tool_calls = 64
max_context_chars = 100000

[checks.test]
cmd = ["npm", "test"]
timeout = 60000
required = true
kind = "test"
filetypes = ["ts"]

Notes that matter:

• Check timeout values are milliseconds; the Ollama timeout is seconds.
• --workspace overrides the config's workspace, and --model overrides every role's model.
• A non-loopback Ollama endpoint is refused unless the config sets ollama.allow_remote = true.
• Default mode is read-only. run and check require --trusted, which is what allows project edits and explicitly configured named checks.
• With no resolvable configuration, every command fails with an error naming the missing configuration — nothing is invented.
• Ollama itself is external: run ollama serve and pull a tool-capable model (for example ollama pull qwen2.5-coder:7b) before expecting runs to work.

Install

npx @reneturcios/agenttrio status --config /path/to/operator.toml

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/agenttrio

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead; mount your config and workspace into the container if you use it that way.

CLI

agenttrio status --config operator.toml
agenttrio run "Fix the failing parser test" --config operator.toml --trusted
agenttrio check --config operator.toml --trusted
agenttrio check test --config operator.toml --trusted

agenttrio --version

Reports print as JSON. Exit codes follow the documented scheme: 0 on success, 1 for a runtime failure (including an unverifiable run configuration), and 2 for usage errors. Arguments are validated before any configuration is read, so a malformed invocation is always a usage error.

The verification gate

A run is reported verified: true only when all of these hold:

• the planner and coder complete within their budgets;
• at least one required named check runs, and every required check passes;
• a separate read-only reviewer returns structured approval (a JSON object with "approved": true).

If the gate fails, the cycle repeats (coder → checks → reviewer) up to max_cycles, and the final report says verified: false with a note naming which condition failed.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server (newline-delimited JSON-RPC):

npx -y @reneturcios/agenttrio mcp --config /path/to/operator.toml --trusted

MCP client configuration:

{
  "mcpServers": {
    "agenttrio": {
      "command": "npx",
      "args": ["-y", "@reneturcios/agenttrio", "mcp", "--config", "/path/to/operator.toml", "--trusted"]
    }
  }
}

Replies carry the report as a JSON text block plus structuredContent; failures are returned as isError results. The server is deliberately sequential.

Tools

The tool list is intentionally only these three tools.

Tool	Input	What it returns
flow_status	{}	The status report: workspace, Ollama reachability and available models, per-role models, agent budgets, and configured checks.
flow_run	{"task": "..."}	The run report: planner/coder output, check results, reviewer decision, cycles used, and the verified gate verdict.
flow_check	{} or {"name": "configured-name"}	The check report: every result for the checks that ran and whether they all passed. Omit name to run all configured checks.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake executor/fetch/runner only)
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.