OpenMinion

Local-first runtime for tool-using AI agents.

GitHub · Website · Docs · Quick Start · Focus Shell · X

openminion is a public alpha release of a Python-first, local-first runtime for tool-using agents.

One shared runtime spans CLI work, Python embedding, HTTP API turns, daemon-backed workflows, tools, sessions, and local integrations, so the system stays inspectable instead of disappearing behind wrappers.

Trust and Brand Safety

• Official GitHub: https://github.com/openminion
• Official website: https://www.openminion.com
• Official X account: https://x.com/OpenMinion

OpenMinion has no official token, coin, NFT, airdrop, staking program, treasury product, or investment offering. Any claim otherwise is unauthorized and should be treated as a scam.

At a glance

• Current public package line: run openminion version or read openminion.base.version.OPENMINION_VERSION
• Best fit today: bounded local workflows, operator-driven runs, tool use on your own machine, and contributors who want a runtime they can inspect
• Main surfaces: CLI, Python API, HTTP API, daemon-backed workflows, tools, providers, sessions, and diagnostics
• Not the claim: OpenMinion is still under active development and should not yet be treated as a finished "give it a complex task and walk away" autonomy system

What OpenMinion provides

openminion currently provides:

• Runtime core: one local runtime with explicit brain, memory, tool, channel, and service ownership boundaries
• User surfaces: focus shell, CLI commands, runtime admin, diagnostics, export, and session-aware operator workflows
• Extension surfaces: package-owned tool hosting, plugin loading, MCP integration, and skill loading
• Integration surfaces: Python/library imports, structured API/runtime entrypoints, configuration profiles, and external service adapters
• Contributor surfaces: examples, scripts, tests, compatibility policy, and repo-local docs for people who want to extend the stack

What OpenMinion does not provide yet

OpenMinion is already useful for bounded local work, but it does not yet claim to be:

• a finished "give it any complex task and walk away" autonomy system
• a hosted control plane or managed cloud service
• a black-box agent wrapper that hides runtime state from the operator
• a token, coin, NFT, airdrop, or investment product of any kind

Quick start

If you only want one successful local run, start here:

export OPENMINION_HOME=.
export OPENMINION_DATA_ROOT="$OPENMINION_HOME/.openminion"
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
python -m openminion config init
python -m openminion run "hello"
python -m openminion tools list
python -m openminion doctor --check-turn --json

If you want the interactive surface next, launch the default focus shell:

python -m openminion

Use the dashboard when you want the monitoring / overview surface across chats, sessions, agents, tools, memory, cron, and system state:

python -m openminion dashboard

Contributor setup

1. Before making code changes, read CONTRIBUTING.md and CODE_QUALITY.md.
2. Keep changes focused, include validation results, and avoid unrelated refactors in the same PR.
3. Use Python 3.11+ and a recent pip with PEP 660 editable-install support.

Local tooling baseline:

make dev-install
make hooks-install
make lint

Core commands:

1. make fix
2. make format
3. make lint
4. make test
5. make check
6. make hooks-run

Validation guidance:

1. use task-scoped pytest or integration commands plus repo-wide ruff check . for normal slice work,
2. use make lint before feature sign-off,
3. treat make check as an optional broad integration sweep, not the default per-task closeout command during multi-agent work,
4. see the package-local testing and validation docs for the public validator inventory and which guards are blocking vs advisory.

Temporary artifact rule:

1. broad cleanup file lists, ledgers, scan outputs, and scratch JSON/TSV/TXT artifacts belong in the repository scratch area rather than in package source or docs roots,
2. durable evidence belongs in maintained project documentation or tracked validation artifacts rather than in package source or package docs roots.

Package layout

src/openminion/
  api/         # public API/runtime entrypoints
  base/        # foundational contracts and shared primitives
  cli/         # CLI entrypoints and interactive UX
  modules/     # feature and subsystem owners
  services/    # cross-owner runtime orchestration
  tools/       # tool runtime host + tool families
docs/
  README.md
  standalone-claim-alignment.md
  certification-readiness-matrix.md
  runtime-surfaces.md
examples/
scripts/
tests/
API_COMPATIBILITY.md
RELEASING.md

Tool package note:

1. src/openminion/tools/ now contains both runtime host files and module-like per-tool folders.
2. Each per-tool folder maps to a previously standalone openminion-tool-* package.
3. Canonical tool imports are openminion.tools.<tool_folder>.

Docs and release

• docs/README.md is the package-local docs entrypoint.
• docs/certification-readiness-matrix.md is the current package-local proof snapshot for the active alpha line.
• docs/runtime-surfaces.md maps the supported CLI, runtime, and Python-library surfaces.
• docs/long-horizon-project-worker.md records the alpha project-worker substrate, proof shape, and current claim boundary for longer objectives.
• API_COMPATIBILITY.md records the supported public import roots and compatibility posture.
• RELEASING.md records the package-local release checks and publish flow.
• docs/source-tree-owner-map.md explains the source-tree layout for contributors who need to go deeper than the public facade.

Focus shell

The default openminion invocation is the recommended interactive surface:

1. openminion launches the terminal-flow focus shell on a TTY. Output stays in your terminal's primary buffer, so scrollback behaves like git log.

2. cat prompt.md | openminion runs one stdin-backed turn and exits.

3. openminion tui also launches focus mode by default. Use openminion dashboard or openminion tui --dashboard when you want the monitoring dashboard across chats, sessions, agents, tools, memory, cron, and system state.

4. openminion focus --rich opens the Textual focus shell with alt-screen, overlays, and an in-app dashboard side-trip.

5. Each agent turn shows a ⏺ marker, verb-rotating thinking spinner, colored ● tool-call markers, and syntax-highlighted code blocks.

6. --plain-spinner drops the verb rotation but keeps the elapsed counter and esc to interrupt hint. The same behavior is available through OPENMINION_FOCUS_PLAIN_SPINNER=1 or NO_COLOR=1.

7. Tool blocks longer than 6 lines are truncated to keep scrollback readable: /expand reprints the latest block, /expand 2 selects the second latest, and /expand 0 lists all truncated blocks.

8. Tool-block verbosity has three levels:

   • --verbosity quiet hides tool blocks but keeps an end-of-turn hidden-call summary.
   • --verbosity normal is the default: 6-line cap plus /expand.
   • --verbosity verbose shows full tool bodies up to a 200-line hard cap.

   You can set the same default with OPENMINION_FOCUS_VERBOSITY=quiet|normal|verbose, then override it live with /quiet, /normal, or /verbose. Failed tool calls show ✗ (exit N) in red after the title.

   For persistent preferences, create <DATA_ROOT>/focus_prefs.toml (usually ~/.openminion/focus_prefs.toml) with flat keys such as verbosity = "quiet" or progress = "off". Precedence is CLI flag → env → preferences file → default.

9. Edit and Write tool calls render inline unified diffs. The same verbosity ladder applies: quiet hides, normal truncates, verbose shows up to 200 lines, and /expand always shows the full diff.

10. Live tool-execution narration prints a yellow ● Running Bash(ls -la) line while a tool is active, then renders the final tool block below it. Quiet mode suppresses narration but still counts the call in the end-of-turn summary.

11. Focus terminal-flow slash commands include /clear, /compact, /cost, /dashboard, /exit, /expand, /help, /init, /mcp, /model, /new, /normal, /quiet, /quit, /readonly, /resume, /sessions, /status, /tools, and /verbose.

    Other composer affordances:

    • prefix ! to run a shell escape;
    • paste an image-file path to convert it to [image: <path>];
    • add custom slash commands as Markdown files in .openminion/commands/*.md or <DATA_ROOT>/commands/*.md; command templates can use $ARGUMENTS, $1..$N, @file, and shell interpolation with ! commands.

Legacy chat surface

openminion chat is in maintenance mode and soft-deprecated as of 2026-05-10:

openminion chat is the legacy interactive REPL surface. It predates the focus shell and continues to work for users who depend on it, but it is no longer the recommended interactive surface. Use openminion (focus terminal-flow) for new work. The repository chat CLI charter records the full maintenance-mode declaration, migration path, and removal criteria. A one-line dim deprecation notice prints on chat launch; suppress it for scripted invocations with OPENMINION_CHAT_NO_DEPRECATION=1.

Chat-only behavior preserved during the notice period:

1. chat shows a waiting spinner by default; disable with chat --no-progress.
2. Suppress INFO logs for cleaner chat UI: chat --quiet.
3. Interactive chat prompt and assistant lines are color-coded in TTY, with [session|agent] context.
4. Prompt format is [session|agent] you>.
5. chat automatically retries transient turn failures once before showing a final error.
6. Provider/API turn failures are non-fatal in chat; the REPL stays open and prints [chat] turn failed: ....
7. Slash commands: /, /help, /status, /clear, /agent, /session, /tools, /artifacts, /debug, /exit.

Cross-surface UX flags

These apply uniformly to focus, gateway, run, and agent surfaces:

1. --verbosity {quiet,normal,verbose} controls tool-block fidelity:
   • quiet hides tool blocks;
   • normal is the default 6-line cap plus /expand;
   • verbose shows full tool bodies up to a 200-line cap.
2. --progress {full,minimal,off} controls in-flight chrome:
   • full is the TTY default with spinner, elapsed time, and interrupt hint;
   • minimal keeps elapsed time and drops verb rotation;
   • off suppresses progress chrome.
3. Auto-detect: when stdin or stdout is piped, --progress defaults to off so captured output stays clean. Pass --progress full to override.
4. Env defaults: OPENMINION_VERBOSITY=quiet|normal|verbose and OPENMINION_PROGRESS=full|minimal|off.
5. Legacy aliases still work: --no-progress → --progress off, --plain-spinner → --progress minimal, and the older focus-specific env vars still resolve with deprecation warnings.
6. NO_COLOR=1 follows the universal convention by mapping to --progress minimal.
7. The Textual --rich shell does NOT yet honor the verbosity ladder. Use the default terminal-flow shell for the full UX.
8. openminion chat is in maintenance mode and does NOT honor the unified --verbosity / --progress flags. It keeps its own existing --no-progress / --quiet flags during the soft-deprecation notice period. The repository chat CLI charter records the current policy.

Shared logging conventions

1. gateway run --quiet suppresses INFO logs for cleaner output.
2. Override log level without editing config: OPENMINION_LOG_LEVEL=WARNING.
3. Keep logs visually secondary in TTY (dim logs); force with OPENMINION_LOG_COLOR=1, disable with OPENMINION_LOG_COLOR=0 or NO_COLOR=1.
4. Disable chat colors with NO_COLOR=1 or OPENMINION_COLOR=0; force with OPENMINION_COLOR=1.

Chat vs gateway loop

1. gateway run is a runtime/operator path with explicit channel/target/once/idempotency controls.
2. Use openminion (focus shell) for conversational UX; use gateway run for operational testing and deterministic runtime controls.
3. For any UI integration or plugin, use gateway ingress (/v1/turn* or GatewayService.run_once) rather than direct agent-service calls. The repository UI gateway contract documents that boundary.
4. openminion chat remains supported during the soft-deprecation notice period for users who depend on its specific affordances; new users should pick focus or gateway instead.

Costs and warranty

OpenMinion is provided on an "as is" basis, without warranties or guarantees of performance, reliability, availability, fitness for a particular purpose, or cost outcomes. To the extent allowed by law, the project and contributors are not liable for damages, losses, outages, billing costs, or other consequences arising from use or malfunction of the software. See LICENSE for the full legal terms and limitations.

OpenMinion can be configured to call third-party providers that may charge usage fees. You are solely responsible for provider, API, cloud, infrastructure, or similar charges incurred through your configuration or use of the software.

Configuration and deeper docs

The package supports multiple runtime backends, profile-based configuration, built-in tools, plugins, skills, storage, and HTTP/runtime integration. Those details are intentionally kept out of the front page so this README stays a generic public entrypoint.

Use these docs when you want to go deeper:

• docs/getting-started.md — package bootstrap and contributor flow
• docs/testing-and-validation.md — smoke checks and release-facing validation commands
• docs/runtime-surfaces.md — CLI, runtime, and library surface map
• docs/long-horizon-project-worker.md — alpha project-worker proof shape and current claim boundary
• docs/source-tree-owner-map.md — source layout guide for contributors
• examples/README.md — runnable examples and starter templates
• API_COMPATIBILITY.md — public import and compatibility posture
• RELEASING.md — package release checklist

License and brand-use boundary

• Source code license: Apache-2.0
• Brand/trademark grant: none

The software license grants rights to use, modify, and redistribute the code. It does not grant rights to use the OpenMinion name, logos, branding, website identity, or social identity except for truthful attribution. Forks, clones, and derivative distributions must not present themselves as the official OpenMinion project or imply affiliation, endorsement, or maintenance by OpenMinion contributors unless that is actually true.