Metadata-Version: 2.5
Name: marim-harness
Version: 0.9.1
Summary: An embeddable coding-agent harness on Pydantic AI, with a Textual TUI and headless mode
Project-URL: Repository, https://github.com/mateuscmarim/marim-harness
Project-URL: Changelog, https://github.com/mateuscmarim/marim-harness/blob/master/CHANGELOG.md
Author-email: Mateus Coutinho Marim <mateus@marim.dev>
License: MIT License
        
        Copyright (c) 2026 Mateus Coutinho Marim
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agent,coding-assistant,llm,pydantic-ai,textual,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: genai-prices>=0.0.70
Requires-Dist: httpx>=0.27
Requires-Dist: jsonschema>=4
Requires-Dist: markdownify>=0.13
Requires-Dist: multilspy>=0.0.10
Requires-Dist: pydantic-ai-slim[google,mcp,openai]<3,>=2.28
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: pyyaml>=6
Provides-Extra: lsp-python
Requires-Dist: basedpyright>=1.13; extra == 'lsp-python'
Provides-Extra: serve
Requires-Dist: segno>=1.6; extra == 'serve'
Requires-Dist: starlette>=0.40; extra == 'serve'
Requires-Dist: uvicorn>=0.30; extra == 'serve'
Provides-Extra: tui
Requires-Dist: flatlatex>=0.15; extra == 'tui'
Requires-Dist: textual>=0.80; extra == 'tui'
Requires-Dist: websockets>=13; extra == 'tui'
Provides-Extra: workflows
Requires-Dist: jsonschema>=4; extra == 'workflows'
Requires-Dist: pydantic-monty<0.1,>=0.0.18; extra == 'workflows'
Description-Content-Type: text/markdown

# 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.

![Marim fixing a bug with two parallel sub-agents: fan-out cards, an edit approval, and a verification run](https://raw.githubusercontent.com/mateuscmarim/marim-harness/master/docs/assets/demo.gif)

[Quickstart](#quickstart) · [Build with Marim](#build-with-marim) ·
[Documentation](https://github.com/mateuscmarim/marim-harness/blob/master/docs/README.md) · [Examples](https://github.com/mateuscmarim/marim-harness/blob/master/examples/README.md)

## Quickstart

Requires **Python 3.10+** and [uv](https://docs.astral.sh/uv/).
Install the interactive terminal UI:

```bash
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.

```bash
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.

```bash
export MARIM_PROVIDER=codex-cli
marim --mode ask
```

### API provider

For OpenRouter, supply your API key:

```bash
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](https://github.com/mateuscmarim/marim-harness/blob/master/docs/reference/configuration.md#provider--model)
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:

```bash
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

| Backend | Marim manages | Backend manages |
| --- | --- | --- |
| API providers / local models | Agent loop, tools, approvals, sessions, and configured MCP/LSP integrations | Model inference |
| Claude Code (`claude-cli`) | Terminal UI, approval requests, and session resume | Claude's agent loop, tools, and authentication |
| Codex (`codex-cli`) | Terminal UI, approval requests, and session resume | Codex's agent loop, tools, sandbox, and authentication |

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](https://github.com/mateuscmarim/marim-harness/blob/master/docs/reference/configuration.md#provider--model).

<details>
<summary>Other installation options</summary>

A bare `uv tool install marim-harness` provides headless mode. Add extras as
needed; they can be combined, for example `marim-harness[tui,serve,workflows]`.

| Extra | Adds |
| --- | --- |
| `tui` | Interactive terminal UI |
| `serve` | HTTP daemon with REST and WebSocket access |
| `workflows` | Sandboxed orchestration scripts |
| `lsp-python` | The basedpyright Python language server |

Both `marim` and `marim-harness` invoke the same console app.

</details>

## Why Marim?

- **An agent loop you can embed.** Compose a Python application with
  `HarnessBuilder`, your model, and your tools. Built on
  [Pydantic AI](https://ai.pydantic.dev/), with a
  [Textual](https://textual.textualize.io/) 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](https://github.com/mateuscmarim/marim-harness/blob/master/docs/guides/trust.md).

## Everyday use

After configuring a provider:

```bash
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](https://github.com/mateuscmarim/marim-harness/blob/master/docs/reference/configuration.md) for defaults.

## Build with Marim

Add the library to your Python project:

```bash
uv add marim-harness
```

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

```python
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](https://github.com/mateuscmarim/marim-harness/blob/master/docs/sdk/README.md),
[custom tools](https://github.com/mateuscmarim/marim-harness/blob/master/docs/sdk/custom-tools.md), or
[embedding examples](https://github.com/mateuscmarim/marim-harness/blob/master/examples/embedding/README.md).

## Documentation

| I want to… | Start here |
| --- | --- |
| Learn shortcuts, image input, and notifications | [Terminal UI](https://github.com/mateuscmarim/marim-harness/blob/master/docs/guides/tui.md) |
| Automate tasks or consume JSON output | [Headless mode](https://github.com/mateuscmarim/marim-harness/blob/master/docs/guides/headless.md) |
| Resume, compact, or rewind a session | [Sessions](https://github.com/mateuscmarim/marim-harness/blob/master/docs/guides/sessions.md) |
| Configure providers, models, and environment variables | [Configuration](https://github.com/mateuscmarim/marim-harness/blob/master/docs/reference/configuration.md) |
| Set permissions and project trust | [Trust](https://github.com/mateuscmarim/marim-harness/blob/master/docs/guides/trust.md) · [Security](https://github.com/mateuscmarim/marim-harness/blob/master/SECURITY.md) |
| Delegate work or orchestrate agents | [Sub-agents](https://github.com/mateuscmarim/marim-harness/blob/master/docs/guides/subagents.md) · [Workflows](https://github.com/mateuscmarim/marim-harness/blob/master/docs/guides/workflows.md) |
| Add instructions, skills, memory, or plugins | [Skills and memory](https://github.com/mateuscmarim/marim-harness/blob/master/docs/guides/skills-and-memory.md) · [Plugins](https://github.com/mateuscmarim/marim-harness/blob/master/docs/plugins.md) |
| Connect tools or lifecycle hooks | [MCP](https://github.com/mateuscmarim/marim-harness/blob/master/docs/guides/mcp.md) · [Hooks](https://github.com/mateuscmarim/marim-harness/blob/master/docs/guides/hooks.md) |
| Run Marim as a service | [HTTP API](https://github.com/mateuscmarim/marim-harness/blob/master/docs/reference/serve-api.md) |

See the [full documentation index](https://github.com/mateuscmarim/marim-harness/blob/master/docs/README.md) for more.

## Contributing

See [CONTRIBUTING.md](https://github.com/mateuscmarim/marim-harness/blob/master/CONTRIBUTING.md) for development setup and checks,
[architecture](https://github.com/mateuscmarim/marim-harness/blob/master/docs/architecture.md) for the codebase map, and the
[quality gate](https://github.com/mateuscmarim/marim-harness/blob/master/docs/quality-gate.md) for maintained quality checks.
[Changes](https://github.com/mateuscmarim/marim-harness/blob/master/CHANGELOG.md) and [planned work](https://github.com/mateuscmarim/marim-harness/blob/master/ROADMAP.md) have their own pages.

## License

[MIT](https://github.com/mateuscmarim/marim-harness/blob/master/LICENSE).
