Autonomous Intelligence

A transaction-safe local action layer for AI agents.

Autonomous Intelligence exposes capability-scoped computer actions through MCP while keeping execution, approval, and crash recovery behind a separate local Broker.

Getting started · Client compatibility · MCP tools · Safety model · Architecture · Contributing

Why this exists

Most desktop-agent prototypes connect probabilistic planning directly to powerful operating-system primitives. That is convenient, but it makes retries, crashes, prompt injection, and ambiguous UI state dangerous.

Autonomous Intelligence draws a hard boundary:

• The MCP adapter and planner are untrusted.

• The Broker derives policy and action class independently.

• Every side effect is represented by a durable operation and attempt.

• Writes require exact, single-use approval.

• Recovery verifies postconditions before retrying.

• An effect that cannot be reconciled becomes UNCERTAIN and stops.

The current release provides a deliberately narrow, production-minded vertical slice for workspace file operations. Windows UI Automation and browser control will be added only when they satisfy the same contracts.

Key guarantees

MCP interface

Autonomous Intelligence is an MCP v2 stdio server with five focused tools:

The autonomous-intelligence://capabilities resource describes the active workspace and safety boundary.

Tool failures are returned through MCP as is_error=true, allowing a host model to correct invalid paths or arguments without mistaking an error string for success.

Client compatibility

The server is model-agnostic and host-neutral. It speaks MCP over stdio and does not call a vendor-specific LLM API.

Use the complete multi-client setup guide for global and project-scoped installation, verification commands, and client-specific approval behavior.

Architecture

flowchart LR
    H["MCP host / AI client"] --> M["Untrusted stdio MCP adapter"]
    M --> E[("Engine journal")]
    E -->|"Authenticated JSON IPC"| B["Execution Broker"]
    B --> U["Human approval"]
    B --> L[("Authoritative Broker ledger")]
    B --> X["Semantic action executor"]
    X --> W["Capability-scoped workspace"]
    E -->|"Status + reconcile"| B

The Broker is not embedded in the MCP process. If the Broker is unavailable, tools fail visibly instead of falling back to direct host access.

Getting started

Requirements

• Windows 10/11

• Python 3.11 or newer

• An MCP host such as Codex, ChatGPT desktop, or another compatible client

Install from source

git clone https://github.com/coldrazer/autonomous-intelligence.git
cd autonomous-intelligence

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

1. Start the Broker

Run the Broker in a visible terminal so write approvals can be reviewed:

autonomous-intelligence --workspace C:\path\to\allowed-workspace broker

The Broker denies writes by default unless the exact operation is approved. --approval-mode allow exists only for disposable automated tests.

2. Connect an LLM client

Generate configuration for any supported host without modifying its files:

autonomous-intelligence --workspace C:\path\to\allowed-workspace `
  client-config claude

Valid client names are codex, claude, kimi, antigravity, gemini, cursor, vscode, and generic.

For Codex, the direct registration command is:

With the virtual environment active:

codex mcp add autonomous-intelligence -- `
  autonomous-intelligence-mcp `
  --workspace C:\path\to\allowed-workspace

Verify the registration:

codex mcp get autonomous-intelligence
codex mcp list

Restart the local Codex client after changing MCP configuration. The ChatGPT desktop app, Codex CLI, and IDE extension share the same Codex MCP configuration.

For manual configuration, add this to ~/.codex/config.toml:

[mcp_servers.autonomous-intelligence]
command = "C:\\path\\to\\autonomous-intelligence\\.venv\\Scripts\\autonomous-intelligence-mcp.exe"
args = ["--workspace", "C:\\path\\to\\allowed-workspace"]
startup_timeout_sec = 20
tool_timeout_sec = 120
default_tools_approval_mode = "auto"

[mcp_servers.autonomous-intelligence.tools.autonomous_write_file]
approval_mode = "prompt"

A generic host configuration is also available in mcp-config.example.json. See docs/CLIENT_SETUP.md for Claude Code, Kimi, Antigravity, Gemini CLI, Cursor, VS Code, and generic stdio clients.

GitHub Container package

Container-oriented MCP hosts can pull the signed multi-platform OCI image:

docker pull ghcr.io/coldrazer/autonomous-intelligence:0.3.1

The native wheel is recommended for Windows desktop use. Container deployments run the Broker and MCP adapter separately with a shared state volume; see the container guide for the exact commands and security boundary.

Direct CLI

The diagnostic CLI uses the same Engine, Broker, policy, and journals:

# Read a workspace file
autonomous-intelligence --workspace C:\workspace read notes.txt

# Create a file; approval occurs in the Broker terminal
autonomous-intelligence --workspace C:\workspace write output.txt `
  --content "verified output"

# Recover attempts after a process restart
autonomous-intelligence --workspace C:\workspace recover

# Stop the Broker
autonomous-intelligence --workspace C:\workspace shutdown

Safety model

Dispatch lifecycle

Engine PREPARED
  → Broker ACCEPTED
  → approval issued and consumed when required
  → Broker IN_FLIGHT
  → semantic effect attempted
  → Broker DELIVERY_ATTEMPTED
  → typed postcondition evaluated
  → Engine VERIFIED

IN_FLIGHT is intentionally conservative: a crash immediately before delivery and one immediately after delivery are indistinguishable until reconciliation.

Recovery behavior

Autonomous Intelligence does not claim exactly-once execution for arbitrary GUI actions or external systems that provide neither idempotency keys nor reliable reconciliation.

Development

Install development dependencies and run the complete suite:

python -m pip install -e ".[dev]"
python -m pytest

The tests cover:

• Journal state transitions and replay conflicts

• Approval denial, expiry, binding, and single use

• Workspace escapes and protected state paths

• Crash recovery before and after side effects

• MCP schemas, annotations, resources, and tool-error semantics

• Host-specific configuration rendering for eight MCP client formats

• The complete Windows subprocess chain: MCP client → stdio server → named pipe → Broker → workspace

See docs/PROTOCOL.md for the wire and recovery contract and docs/IMPLEMENTATION_STATUS.md for current scope and roadmap.

Roadmap

• Transactional Engine and authoritative Broker ledger

• Capability-scoped semantic file actions

• MCP v2 stdio adapter

• Codex, Claude, Kimi, Antigravity, Gemini, Cursor, and VS Code setup assets

• Multi-platform GitHub Container package with SBOM and provenance

• Windows named-pipe integration tests

• Read-only Windows UI Automation observation adapter

• Structural UI fingerprints and ambiguity rejection

• Human-input contention detection

• Browser CDP adapter with origin and frame binding

• Hardened Windows service identity, ACLs, and signed installer

Security

Please read SECURITY.md before deploying or reporting a vulnerability. The current release is an evaluated local vertical slice—not a claim that unrestricted autonomous desktop control is safe.

Contributing

Contributions are welcome when they preserve the transaction and policy boundary. Start with CONTRIBUTING.md.

License

Released under the MIT License.