OpenPlanter

A recursive-language-model investigation agent with a rich CLI/TUI, 86 built-in tools spanning financial forensics, blockchain analysis, prediction markets, regulatory filings, and social intelligence. Designed to be imported as a module into Node.js/TypeScript projects or used standalone via the CLI.

Installation

npm install openplanter

Requires Node.js >= 18.0.0.

Quick Start

As a CLI

# Configure API keys (interactive prompt)
npx openplanter-agent --configure-keys

# Launch the TUI
npx openplanter-agent --workspace /path/to/project

# Run a single task headlessly
npx openplanter-agent --task "Analyse recent director trades for BHP" --workspace ./data

As a Module

import { buildEngine, agentConfigFromEnv } from "openplanter";

const config = agentConfigFromEnv("./workspace");
const engine = await buildEngine(config);

Import specific submodules for lighter bundles:

import { RLMEngine } from "openplanter/engine";
import { Conversation, OpenAICompatibleModel } from "openplanter/model";
import { WorkspaceTools } from "openplanter/tools";
import { agentConfigFromEnv } from "openplanter/config";

Investigation Tools

All investigation tools are available as typed async functions:

import {
  priceFetcher,
  volumeScanner,
  entityResolver,
  insiderGraph,
  insiderSuspicionScorer,
  timelineLinker,
  aphHoldings,
  asicOfficerLookup,
  asxCalendarFetcher,
  asxParser,
  bulkAsxAnnouncements,
  hotcopperScraper,
  multiForumScraper,
  polymarketMarkets,
  predictionMarkets,
  duneAnalytics,
  blockchainScanner,
  dexscreenerPairs,
  walletClusterer,
  secTools,
  politicalFinance,
  globalRegistries,
  governmentRecords,
  socialIntelligence,
  advancedAnalytics,
  documentProcessing,
  investigationAutomation,
  monitoringTools,
  cryptoEcosystem,
} from "openplanter/investigation-tools";

// Fetch price data from Yahoo Finance
const ohlcv = await priceFetcher.fetchOhlcv(["BHP", "RIO"], "3mo", "1d");

// Scan for volume/price anomalies
const anomalies = await volumeScanner.scanTickers(["BHP"], 60);

// Fetch all ASX tickers and their 4C calendar data
const calendar = await asxCalendarFetcher.fetchCalendar({ tickers: "all", period: "next_90d" });

// Fetch calendar for specific tickers
const bhpCalendar = await asxCalendarFetcher.fetchCalendar({ tickers: "BHP,RIO,WES", period: "Q1_2026" });

// Resolve entities across datasets
const resolved = entityResolver.modeResolve(entities, 80);

// Build and analyse an insider trading graph
const graph = insiderGraph.buildGraph(graphData);
const path = insiderGraph.findShortestPath(graph, "person-1", "event-1");

// Score trades for suspicion
const scores = insiderSuspicionScorer.scoreTrades(trades, anomalyData, rumors, holdings);

// Correlate trades with announcements
const correlations = timelineLinker.correlate(trades, events);

Or import individual tools directly:

import { fetchOhlcv, computeMetrics } from "openplanter/investigation-tools/price-fetcher";
import { scrapeHotcopper } from "openplanter/investigation-tools/hotcopper-scraper";
import { fetchAllAsxTickers, fetchCalendar } from "openplanter/investigation-tools/asx-calendar-fetcher";

Supported Providers

| Provider | Default Model | Env Var | |----------|---------------|---------| | OpenAI | gpt-5.2 | OPENAI_API_KEY | | Anthropic | claude-opus-4-6 | ANTHROPIC_API_KEY | | OpenRouter | anthropic/claude-sonnet-4-5 | OPENROUTER_API_KEY | | Cerebras | qwen-3-235b-a22b-instruct-2507 | CEREBRAS_API_KEY | | Grok (xAI) | grok-4-1-fast-reasoning | XAI_API_KEY / GROK_API_KEY |

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, or via CLI flags.

Agent Tools

The agent has access to 86 tools organized into core workspace operations and domain-specific investigation modules.

Core Tools (19)

• Workspace -- list_files, search_files, repo_map, read_file, write_file, edit_file, hashline_edit, apply_patch
• Shell -- run_shell, run_shell_bg, check_shell_bg, kill_shell_bg
• Web -- web_search (Exa), fetch_url
• Planning -- think, subtask, execute, list_artifacts, read_artifact

In recursive mode (the default), the agent spawns sub-agents via subtask and execute.

Australian Market Tools (13)

| Tool | Description | |------|-------------| | aph_holdings | Scrape APH politician holdings disclosures | | asx_parser | Parse ASX announcements (Appendix 3Y, 4C, trading halts) | | asx_calendar_fetcher | Fetch ASX Appendix 4C quarterly reporting calendar (supports all tickers via ASX company directory) | | bulk_asx_announcements | Bulk-fetch ASX announcements (3Y, 4C, 3B) for multiple tickers | | asic_officer_lookup | Query ASIC/ABR for company officers and directors by ABN or ticker | | entity_resolver | Fuzzy entity matching and resolution across Australian datasets | | hotcopper_scraper | Scrape HotCopper stock forum for ticker sentiment and rumors | | multi_forum_scraper | Aggregate sentiment from HotCopper and other forums | | insider_graph | Build and analyse entity-event relationship graphs | | insider_suspicion_scorer | Composite insider-trading suspicion scoring | | price_fetcher | Yahoo Finance OHLCV data and technical metrics | | timeline_linker | Correlate trades with announcements on a timeline | | volume_scanner | Detect unusual volume and price anomalies |

Prediction Markets (9)

| Tool | Description | |------|-------------| | polymarket_markets_fetcher | Fetch active Polymarket markets | | polymarket_leaderboard | Polymarket leaderboard data | | polymarket_whales | Track Polymarket whale positions | | polymarket_trades_history | Historical Polymarket trade data | | polymarket_resolutions | Polymarket market resolutions | | polymarket_anomaly_scanner | Detect anomalies in Polymarket activity | | kalshi_markets | Kalshi prediction market data | | predictit_markets | PredictIt market data | | manifold_markets | Manifold Markets data |

Blockchain & Crypto (8)

| Tool | Description | |------|-------------| | dune_query_executor | Execute Dune Analytics queries | | dune_polymarket | Dune queries for Polymarket on-chain data | | dune_tx_timings | Analyse transaction timing patterns | | polygonscan_wallet | Polygon wallet transaction data | | etherscan_wallet | Ethereum wallet transaction data | | blockchain_tx_tracer | Trace blockchain transaction flows | | dexscreener_pairs | DEXScreener token pair data | | wallet_clusterer | Cluster related wallet addresses |

SEC & US Regulatory (3)

| Tool | Description | |------|-------------| | sec_form4_parser | Parse SEC Form 4 insider trading filings | | sec_edgar_filer | Search SEC EDGAR filer database | | sec_whistleblower_awards | SEC whistleblower award data |

Political Finance (4)

| Tool | Description | |------|-------------| | fec_contributions | FEC campaign contribution records | | opensecrets_lobbying | OpenSecrets lobbying disclosure data | | congress_disclosures | Congressional financial disclosures | | political_donation_tracker | Cross-border political donation tracking |

Global Registries (3)

| Tool | Description | |------|-------------| | opencorporates_lookup | OpenCorporates company registry search | | ofac_sanctions_checker | OFAC sanctions list screening | | beneficial_ownership_tracer | Trace beneficial ownership chains |

Government Records (3)

| Tool | Description | |------|-------------| | us_court_docket | US court docket and case search | | federal_contracts | Federal contract award records | | foia_request_builder | Generate FOIA request templates |

Social Intelligence (6)

| Tool | Description | |------|-------------| | twitter_market_mentions | Track market-related Twitter/X mentions | | reddit_wsb_scanner | Scan Reddit WallStreetBets and related subs | | discord_channel_scraper | Scrape Discord channel messages | | telegram_channel_monitor | Monitor Telegram channels | | news_sentiment_fetcher | Fetch and score news article sentiment | | substack_scraper | Scrape Substack newsletter content |

Advanced Analytics (4)

| Tool | Description | |------|-------------| | anomaly_detector_ts | Time-series anomaly detection | | timeline_correlator | Cross-dataset timeline correlation | | network_centrality_analyzer | Graph centrality and influence analysis | | prediction_market_arbitrage | Detect prediction market arbitrage opportunities |

Document Processing (3)

| Tool | Description | |------|-------------| | pdf_filings_extractor | Extract structured data from PDF filings | | document_similarity_scorer | Score document similarity | | sentiment_analyzer | General-purpose text sentiment analysis |

Investigation Automation (5)

| Tool | Description | |------|-------------| | cross_reference_engine | Cross-reference entities across multiple data sources | | insider_network_expander | Expand insider networks via graph traversal | | compliance_risk_report | Generate compliance risk assessment reports | | global_entity_resolver | Resolve entities across international registries | | jurisdiction_risk_scorer | Score jurisdictional risk for entities |

Monitoring (4)

| Tool | Description | |------|-------------| | whale_alert_monitor | Monitor large crypto/market transactions | | dark_pool_activity | Track dark pool trading activity | | corporate_filings_monitor | Monitor new corporate filings | | real_estate_records | Property ownership record search |

Crypto Ecosystem (2)

| Tool | Description | |------|-------------| | gitcoin_grants_parser | Parse Gitcoin grant data | | evidence_graph_builder | Build evidence graphs from investigation data |

CLI Reference

openplanter-agent [options]

| Flag | Description | |------|-------------| | --workspace <dir> | Workspace root directory (default: .) | | --model <name> | Model name override | | --default-model <name> | Persist workspace default model | | --default-model-openai <name> | Persist default model for OpenAI provider | | --default-model-anthropic <name> | Persist default model for Anthropic provider | | --default-model-openrouter <name> | Persist default model for OpenRouter provider | | --default-model-cerebras <name> | Persist default model for Cerebras provider | | --default-model-grok <name> | Persist default model for Grok (xAI) provider | | --base-url <url> | Provider base URL override | | --api-key <key> | Legacy API key alias (maps to OpenAI) | | --openai-api-key <key> | OpenAI API key override | | --anthropic-api-key <key> | Anthropic API key override | | --openrouter-api-key <key> | OpenRouter API key override | | --cerebras-api-key <key> | Cerebras API key override | | --grok-api-key <key> | Grok (xAI) API key override | | --exa-api-key <key> | Exa API key override | | --voyage-api-key <key> | Voyage API key override | | --configure-keys | Interactive key configuration | | --task <objective> | Run a single task and exit (headless) | | --recursive | Enable recursive sub-agent delegation | | --max-depth <n> | Maximum recursion depth (default: 4) | | --max-steps <n> | Maximum steps per recursive call (default: 100) | | --timeout <n> | Shell command timeout in seconds (default: 45) | | --headless | Disable interactive UI/prompts (for CI) | | --no-tui | Plain REPL (no colors or spinner) | | --session-id <id> | Session id to use | | --resume | Resume an existing session | | --list-sessions | List known sessions and exit | | --list-models | Fetch and list available provider models | | --acceptance-criteria | Enable acceptance criteria judging | | --demo | Censor entity names in output | | --show-settings | Show persistent workspace defaults and exit |

TUI Commands

| Command | Action | |---------|--------| | /model | Show current model, provider, and aliases | | /model <name> | Switch model (e.g. /model opus, /model gpt5) | | /model <name> --save | Switch model and persist as workspace default | | /model list [all] | List available models | | /reasoning [low\|medium\|high\|off] | Show or change reasoning effort | | /status | Show session status, provider, and token usage | | /clear | Clear the screen | | /quit or /exit | Exit | | /help | Show command help |

Model Aliases

| Alias | Model | |-------|-------| | opus / opus4.6 | claude-opus-4-6 | | sonnet / sonnet4.5 | claude-sonnet-4-5-20250929 | | haiku / haiku4.5 | claude-haiku-4-5-20251001 | | gpt5 / gpt5.2 | gpt-5.2 | | gpt4 / gpt4.1 | gpt-4.1 | | gpt4o | gpt-4o | | o4 / o4-mini | o4-mini | | o3 / o3-mini | o3-mini | | cerebras / qwen235b | qwen-3-235b-a22b-instruct-2507 | | oss120b | gpt-oss-120b | | grok / grok41fast | grok-4-1-fast-reasoning | | grok3mini | grok-3-mini | | grok4 | grok-4-0709 | | grok4fast | grok-4-fast-reasoning |

Configuration

Keys are resolved in priority order:

1. CLI flags (--openai-api-key, --anthropic-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)

Environment Variables

All engine parameters can be configured via environment variables with the OPENPLANTER_ prefix:

| Variable | Default | Description | |----------|---------|-------------| | OPENPLANTER_PROVIDER | auto | Provider selection | | OPENPLANTER_MODEL | claude-opus-4-6 | Model name | | OPENPLANTER_REASONING_EFFORT | high | Reasoning effort level | | OPENPLANTER_MAX_DEPTH | 4 | Maximum recursion depth | | OPENPLANTER_MAX_STEPS | 100 | Maximum steps per call | | OPENPLANTER_CMD_TIMEOUT | 45 | Shell command timeout (seconds) | | OPENPLANTER_RECURSIVE | true | Enable recursive mode | | OPENPLANTER_DEMO | false | Censor entity names | | OPENPLANTER_ABR_GUID | (none) | ABR API GUID for ASIC officer lookups (register at https://abr.business.gov.au) | | OPENPLANTER_MAX_OBS_CHARS | 6000 | Max observation characters | | OPENPLANTER_MAX_FILES | 400 | Max files listed | | OPENPLANTER_MAX_FILE_CHARS | 20000 | Max file read characters | | OPENPLANTER_MAX_SEARCH_HITS | 200 | Max search result hits | | OPENPLANTER_MAX_SHELL_CHARS | 16000 | Max shell output characters | | OPENPLANTER_SESSION_DIR | .openplanter | Session root directory | | OPENPLANTER_SHELL | /bin/sh | Shell for command execution |

Project Structure

src/
  index.ts                  Library entry point
  cli.ts                    CLI entry point and REPL
  engine.ts                 Recursive language model engine
  runtime.ts                Session persistence and lifecycle
  model.ts                  Provider-agnostic LLM abstraction
  builder.ts                Engine/model factory
  tools.ts                  Workspace tool implementations
  tool-defs.ts              Tool JSON schemas (86 tools)
  prompts.ts                System prompt construction
  config.ts                 Configuration and provider defaults
  credentials.ts            Credential management and discovery
  tui.ts                    Rich terminal UI with slash commands
  demo.ts                   Demo mode (output censoring)
  patching.ts               File patching utilities
  settings.ts               Persistent workspace settings
  replay-log.ts             Replay logging
  investigation-tools/
    index.ts                Barrel export for all investigation modules
    shared.ts               HTTP helpers, date parsing, sentiment, normalization
    shared-crypto.ts        Shared crypto/blockchain utilities
    tool-registry.ts        Investigation tool dispatch registry
    aph-holdings.ts         APH politician holdings scraper
    asic-officer-lookup.ts  ASIC officer/director lookup
    asx-calendar-fetcher.ts ASX 4C calendar (supports all ~2,000 ASX tickers)
    asx-parser.ts           ASX announcement parser (3Y, 4C, halts)
    bulk-asx-announcements.ts Bulk ASX announcement fetcher
    entity-resolver.ts      Fuzzy entity matching and resolution
    hotcopper-scraper.ts    HotCopper forum scraper
    insider-graph.ts        Entity-event graph analysis
    insider-suspicion-scorer.ts Composite suspicion scorer
    multi-forum-scraper.ts  Multi-forum sentiment aggregator
    price-fetcher.ts        Yahoo Finance OHLCV data and metrics
    timeline-linker.ts      Trade-announcement timeline correlation
    volume-scanner.ts       Volume/price anomaly scanner
    polymarket-markets.ts   Polymarket market data tools
    prediction-markets.ts   Kalshi, PredictIt, Manifold data
    dune-analytics.ts       Dune Analytics query tools
    blockchain-scanner.ts   Blockchain transaction tracing
    dexscreener-pairs.ts    DEXScreener token pair data
    wallet-clusterer.ts     Wallet address clustering
    sec-tools.ts            SEC EDGAR, Form 4, whistleblower tools
    political-finance.ts    FEC, OpenSecrets, Congress disclosures
    global-registries.ts    OpenCorporates, OFAC, beneficial ownership
    government-records.ts   Court dockets, federal contracts, FOIA
    social-intelligence.ts  Twitter, Reddit, Discord, Telegram, news
    advanced-analytics.ts   Anomaly detection, centrality, arbitrage
    document-processing.ts  PDF extraction, similarity, sentiment
    investigation-automation.ts Cross-reference, network expansion, compliance
    monitoring-tools.ts     Whale alerts, dark pools, filings, real estate
    crypto-ecosystem.ts     Gitcoin grants, evidence graph builder

Development

npm install
npm run build      # Compile TypeScript
npm run lint       # Type-check without emitting
npm run dev        # Run CLI via tsx (development)
npm test           # Run tests (vitest)

License

MIT