OpenPlanter

A recursive-language-model investigation agent with a terminal UI. OpenPlanter ingests heterogeneous datasets — corporate registries, campaign finance records, lobbying disclosures, government contracts, and more — resolves entities across them, and surfaces non-obvious connections through evidence-backed analysis. It operates autonomously with file I/O, shell execution, web search, and recursive sub-agent delegation.

Quickstart

# Installpip install -e .​# Configure API keys (interactive prompt)openplanter-agent --configure-keys​# Launch the TUIopenplanter-agent --workspace /path/to/your/project

Or run a single task headlessly:

openplanter-agent --task "Cross-reference vendor payments against lobbying disclosures and flag overlaps" --workspace ./data

Docker

# Add your API keys to .env, then:docker compose up

The container mounts ./workspace as the agent's working directory.

Supported Providers

Additional service keys: EXA_API_KEY (web search), VOYAGE_API_KEY (embeddings).

All keys can also be set with an OPENPLANTER_ prefix (e.g. OPENPLANTER_OPENAI_API_KEY), via .env files in the workspace, or via CLI flags.

Agent Tools

The agent has access to 19 tools, organized around its investigation workflow:

Dataset ingestion & workspace — list_files, search_files, repo_map, read_file, write_file, edit_file, hashline_edit, apply_patch — load, inspect, and transform source datasets; write structured findings.

Shell execution — run_shell, run_shell_bg, check_shell_bg, kill_shell_bg — run analysis scripts, data pipelines, and validation checks.

Web — web_search (Exa), fetch_url — pull public records, verify entities, and retrieve supplementary data.

Planning & delegation — think, subtask, execute, list_artifacts, read_artifact — decompose investigations into focused sub-tasks, each with acceptance criteria and independent verification.

In recursive mode (the default), the agent spawns sub-agents via subtask and execute to parallelize entity resolution, cross-dataset linking, and evidence-chain construction across large investigations.

CLI Reference

openplanter-agent [options]

Workspace & Session

Model Selection

Execution

UI

Persistent Defaults

Use --default-model, --default-reasoning-effort, or per-provider variants like --default-model-openai to save workspace defaults to .openplanter/settings.json. View them with --show-settings.

TUI Commands

Inside the interactive REPL:

Configuration

Keys are resolved in this priority order (highest wins):

1. CLI flags (--openai-api-key, etc.)
2. Environment variables (OPENAI_API_KEY or OPENPLANTER_OPENAI_API_KEY)
3. .env file in the workspace
4. Workspace credential store (.openplanter/credentials.json)
5. User credential store (~/.openplanter/credentials.json)

All runtime settings can also be set via OPENPLANTER_* environment variables (e.g. OPENPLANTER_MAX_DEPTH=8).

Project Structure

agent/  __main__.py    CLI entry point and REPL  engine.py      Recursive language model engine  runtime.py     Session persistence and lifecycle  model.py       Provider-agnostic LLM abstraction  builder.py     Engine/model factory  tools.py       Workspace tool implementations  tool_defs.py   Tool JSON schemas  prompts.py     System prompt construction  config.py      Configuration dataclass  credentials.py Credential management  tui.py         Rich terminal UI  demo.py        Demo mode (output censoring)  patching.py    File patching utilities  settings.py    Persistent settingstests/           Unit and integration tests

Development

# Install in editable modepip install -e .​# Run testspython -m pytest tests/​# Skip live API testspython -m pytest tests/ --ignore=tests/test_live_models.py --ignore=tests/test_integration_live.py

Requires Python 3.10+. Dependencies: rich, prompt_toolkit, pyfiglet.

License

See VISION.md for the project's design philosophy and roadmap.