How ruc-nlpir/arbor works
1. What this repo is
Arbor is a Python-first autonomous research system packaged as the arbor CLI. Its architecture is centered on a Coordinator + Executor split: the Coordinator plans and branches ideas, while Executors run isolated experiments and feed results back into the Idea Tree.
2. Core runtime boundary
The main runtime lives under src/core/ and provides shared infrastructure: agent abstractions, config loading/resolution, context management, LLM provider adapters, tool abstractions, logging, OAuth, and skill loading. This is the shared foundation used by both the Coordinator and Executor processes.
3. Coordinator subsystem
src/coordinator/ is the decision-making engine. It owns the Idea Tree, orchestrates the “arbor cycle” (observe → ideate → select → dispatch → backpropagate → decide), and applies higher-level policies like convergence, contamination checks, context pruning, and human-in-the-loop gating.
4. Executor subsystem
src/executor/ is the implementation/evaluation worker. It takes one hypothesis, edits code, runs the benchmark or task, and reports evidence. The important architectural boundary is that Executors operate in isolated git worktrees, so experimental changes stay separated from the main branch until a merge decision is made.
5. Experiment and repository safety
The repo treats the target project as a sandboxed external workspace. Tools under src/coordinator/tools/, src/core/tools/, and src/zoo/ enforce protected file access, git/worktree operations, evaluation execution, and integrity checks. This is the mechanism that keeps Arbor from directly mutating the user’s main repository state during exploration.
6. CLI and user-facing control plane
src/cli/ is the operator-facing shell. It handles startup, intake conversation, configuration, setup, login, doctoring, replay, export, run control, dashboard launching, and resume/picker flows. It is the main entry point for interactive use and the place where goals are turned into a concrete research contract.
7. Session state, events, and observability
Arbor is event-driven. src/events/ defines the event bus, payloads, subscribers, and stats collection. Runs emit structured events to session artifacts such as events.jsonl, tree snapshots, stats, and reports. Those artifacts are then consumed by replay, export, dashboard, and the web UI.
8. Reporting and replay
src/report/, src/dashboard.py, src/cli/replay.py, and src/cli/tree_export.py turn session data into human-readable outputs. The architecture clearly separates execution from presentation: the run produces structured artifacts first, and the report/dashboard layers render them afterward.
9. Search and novelty checking
Arbor can ground ideas in prior art through src/core/tools/web/ and the search-oriented parts of src/coordinator/tools/ and src/search_agent/. The built-in alphaXiv-backed path is used for novelty checks and related-work summaries, either manually via arbor idea-check or automatically when new ideas are added to the tree.
10. Extension model: plugins, skills, and MCP
Domain customization comes from two layers: YAML plugins under src/plugins/ and markdown skills under skills/ and src/skills/. For keyless usage inside Claude Code/Codex-style hosts, src/mcp/ exposes Arbor’s deterministic tools over MCP so the host model can drive the loop without Arbor needing its own API key.
11. Benchmark zoo and task packaging
The benchmark ecosystem lives in src/zoo/, arbor-zoo/, and examples/. This layer handles acquiring benchmark assets, scaffolding new tasks, packing/verifying benchmark bundles, and defining task-specific eval contracts. It is the boundary where Arbor generalizes from “one repo optimization run” to reusable benchmark definitions.
12. External service and model boundary
Model access is abstracted behind provider adapters in src/core/llm/ and OAuth helpers in src/core/oauth/. The runtime can speak to Anthropic, OpenAI/Responses, OpenAI-compatible endpoints via LiteLLM-style backends, and keyless host-driven modes. This is a clean separation between Arbor’s orchestration logic and the actual model backend.
13. Delivery surfaces
The repository also ships a static marketing/docs surface: MkDocs content under docs/ and a React/Vite project under project_page/ for the public website and demo assets. These are presentation-only surfaces; they don’t participate in the core research loop, but they mirror the same concepts in a browser-friendly form.
14. How data flows end to end
A typical run flows from CLI intake → config resolution → Coordinator planning → Executor worktree execution → event emission and artifact capture → merge/prune decision → report/dashboard replay. The key architectural idea is that Arbor learns by accumulating structured tree state and run artifacts, not by keeping everything in transient chat context.
Main entry points: app.py arbor CLI · orchestrator.py Coordinator · main.py Executor · bus.py Event bus
Components 25
CLI
Operator-facing entrypoints and run control
- arbor CLI · Main command shell and startup wiring
src/cli/app.py - Commands · Subcommands for setup, run, login, replay, export, web, and diagnostics
src/cli/commands - Intake flow · Conversation capture, goal intake, and research contract setup
src/cli/intake - Resume tools · Resume picker, run state, and post-run handling
src/cli/resume_picker.py
Core runtime
Shared agent, config, tool, and model infrastructure
- Config system · Schema, resolution, CLI config, and user settings
src/core/config_resolve.py - Agent core · Shared agent abstractions and execution scaffolding
src/core/agent.py - Tooling · File, shell, skill, executor, and web tools
src/core/tools - LLM adapters · Provider adapters for Anthropic, OpenAI, and compatible backends
src/core/llm
Coordinator
Planning, idea tree, and policy loop
- Coordinator · Owns arbor cycle orchestration and high-level policy
src/coordinator/orchestrator.py - Idea tree · Branching hypothesis tree and checkpoints
src/coordinator/idea_tree.py - Policies · Contamination, convergence, pruning, and human-in-the-loop checks
src/coordinator/contamination.py - Coord tools · Protected file access, git/worktree ops, executor dispatch, and findings capture
src/coordinator/tools
Executor
Isolated experiment runner
- Executor · Isolated hypothesis execution and evaluation worker
src/executor/main.py
Events and reporting
Run artifacts, replay, and presentation layers
- Event bus · Structured event emission, payloads, and subscribers
src/events/bus.py - Reports · Human-readable summaries and run reports
src/report/generator.py - Dashboard · Session browser and web dashboard entrypoint
src/dashboard.py - Web UI · Static session viewer and browser-based UI
src/webui/server.py
Extensions
Plugins, skills, search, and MCP integration
- Search agent · Research and related-work search orchestration
src/search_agent/agent.py - Plugins · Domain-specific plugin manifests and behavior hooks
src/plugins - Skills · Reusable markdown skills for coordinator, executor, search, and setup flows
skills - MCP server · Exposes deterministic Arbor tools to host models
src/mcp/server.py
Benchmark zoo
Benchmark packaging and task scaffolding
- Benchmark zoo · Acquire, scaffold, pack, verify, and collect benchmark tasks
src/zoo - Zoo assets · Packaged benchmark templates and example tasks
arbor-zoo
Connections 29
- arbor CLI → Commands: dispatches · CLI entrypoint routes to command handlers
- arbor CLI → Intake flow: starts intake · Interactive setup collects research goals
- arbor CLI → Config system: resolves config · Startup loads and merges user and run configuration
- arbor CLI → Coordinator: launches loop · CLI run starts the coordinator orchestration cycle
- arbor CLI → Executor: spawns workers · Execution commands invoke isolated executor runs
- arbor CLI → Dashboard: opens dashboard · Operator can launch a local session dashboard
- arbor CLI → MCP server: serves tools · CLI can expose Arbor over MCP for host-driven use
- Coordinator → Idea tree: updates tree · Coordinator reads and mutates the idea tree
- Coordinator → Policies: applies policy · Decision loop consults pruning, contamination, and HITL checks
- Coordinator → Coord tools: dispatches tools · Coordinator uses protected repo and executor-control tools
- Coordinator → Event bus: emits events · Coordinator publishes structured lifecycle events
- Coord tools → Executor: runs experiments · Coordinator launches executor worktree jobs
- Coord tools → Tooling: reuses primitives · Coordination tools build on shared file and shell abstractions
- Executor → Tooling: edits and runs · Executor uses shared tool primitives to modify code and run tasks
- Executor → LLM adapters: calls model · Executor agents rely on model adapters for reasoning and actions
- Executor → Event bus: reports evidence · Executor emits structured results and evaluation events
- Event bus → Reports: feeds reports · Event stream becomes run summaries and reports
- Event bus → Dashboard: feeds live view · Dashboard consumes session events and snapshots
- Event bus → Web UI: feeds UI · Web UI renders stored session artifacts
- Search agent → Tooling: searches web · Search flows use web tools and related-work retrieval
- Plugins → Coord tools: extends behavior · Plugins add domain-specific orchestration and evaluation hooks
- Skills → Agent core: prompt assets · Skills guide shared agent behavior across roles
- Skills → Coordinator: specializes roles · Coordinator-oriented skills define planner behaviors
- Skills → Executor: specializes roles · Executor-oriented skills define worker behaviors
- Benchmark zoo → Zoo assets: packages tasks · Zoo subsystem manages benchmark templates and example bundles
- Benchmark zoo → Tooling: uses tools · Benchmark acquisition and verification rely on shared tooling
- MCP server → Tooling: exposes tools · MCP server publishes deterministic tools to external hosts
- Docs → arbor CLI: documents · Docs explain the CLI and user workflows
- Website → Reports: showcases · Public site mirrors reports and demo outputs