marim-harness

A terminal coding agent you can also build on.

Use Marim to work on your code with streaming responses, tool approvals, and resumable sessions—or embed its agent loop in your own Python application. Connect Claude Code or Codex through their CLI backends, or use models through API providers and local servers.

Quickstart · Build with Marim · Documentation · Examples

Quickstart

Requires Python 3.10+ and uv. Install the interactive terminal UI:

uv tool install 'marim-harness[tui]'

In your project directory, choose one of the setups below. Each launches Marim in ask mode so you can review approval requests. Then try: “Explain how this project is organized and where its tests live.”

Claude Code

Install Claude Code 2.1+ and sign in through claude first. The claude executable must be on your PATH; Marim uses the CLI's authentication.

export MARIM_PROVIDER=claude-cli
marim --mode ask

Codex

Install Codex CLI 0.152+ and sign in with codex login first. The codex executable must be on your PATH; Marim uses the CLI's authentication.

export MARIM_PROVIDER=codex-cli
marim --mode ask

API provider

For OpenRouter, supply your API key:

export MARIM_PROVIDER=openrouter
export OPENROUTER_API_KEY='your-api-key'
marim --mode ask

Google, OpenCode Zen, and Zen Go are also supported. See provider configuration for credentials and model selection.

Local model

Start an OpenAI-compatible server such as Ollama or LM Studio with a model available before launching Marim. No cloud API key is needed:

export MARIM_PROVIDER=local
export MARIM_BASE_URL=http://localhost:11434/v1  # LM Studio: http://localhost:1234/v1
export MARIM_API_KEY=local
marim --mode ask

Choose a model from the server in Marim's model picker. Set MARIM_MODEL explicitly for headless runs.

Choose your backend

Marim's native tools and MCP/LSP configuration apply to API/local backends. The CLI backends have separate integration and configuration limits; see provider details.

Why Marim?

• An agent loop you can embed. Compose a Python application with HarnessBuilder, your model, and your tools. Built on Pydantic AI, with a Textual terminal UI.
• Continuity across tasks. Resume conversations, steer running work, and rewind conversation and workspace checkpoints. File snapshots require Git and honor .gitignore.
• Delegation with control. Run background jobs and sub-agents with selected tools and model tiers. Add workflows for scripted orchestration.
• Context and extensions. Configure language servers for definitions, references, and diagnostics; connect MCP tools; add instructions, skills, persistent memory, and plugins.
• Explicit permissions. Choose ask, auto, or read-only plan mode. Native shell tools support command policies. Project-local hooks and MCP require trust, remembered through the first-open prompt, /trust, or marim trust grant. See the trust guide.

Everyday use

After configuring a provider:

marim /path/to/workspace    # work in a specific project
marim --resume              # resume this workspace's latest session
marim sessions             # inspect saved sessions
marim config               # view configuration

# Headless prompts for scripts and CI
marim -p "Explain this project's test setup" --mode plan
marim -p "Summarize the README" --output-format json --mode plan

In the TUI, use /model, /settings, and /help to explore. Configuration can live in shell variables or .env files; shell variables take precedence. See the configuration reference for defaults.

Build with Marim

Add the library to your Python project:

uv add marim-harness

With OPENROUTER_API_KEY exported, this runs a turn using the same native agent engine that powers the terminal app:

import asyncio
from pathlib import Path

from marim_harness import HarnessBuilder


async def main() -> None:
    harness = HarnessBuilder(
        workspace=Path("."),
        model="openrouter:anthropic/claude-sonnet-4-6",
    ).build()
    outcome = await harness.run_turn("Explain what the README says this project does")
    print(outcome.result)


asyncio.run(main())

A bare builder provides file tools and an in-memory session in auto mode. Add shell tools, sessions, sub-agents, and integrations explicitly. Builder configuration is explicit; model credentials follow Pydantic AI's provider conventions, without loading Marim's .env files.

Start with the SDK guide, custom tools, or embedding examples.

Documentation

See the full documentation index for more.

Contributing

See CONTRIBUTING.md for development setup and checks, architecture for the codebase map, and the quality gate for maintained quality checks. Changes and planned work have their own pages.

License

MIT.