Holon

Open-source AI assistants on your own computer or server. Assign tasks, track progress, and let them follow up on ongoing work.
Skip to content
Browse docs
On this page

Build an AI Agent ecosystem researcher for multi-repo research

Tracking rapidly evolving technical domains—such as AI agent frameworks, runtimes, and protocols—is difficult with one-off chat sessions or basic web searches:

  • Lack of primary source evidence: Web summaries and second-hand blog posts quickly become outdated or imprecise. Definitive technical details live in source code architectures, commit histories, release notes, and test suites.
  • Context pollution across multiple repositories: Technical evaluation requires comparing multiple independent open-source projects (such as different test harnesses, runtime schedulers, or protocols). Confining an agent to a single directory prevents cross-repo comparison; letting an agent write notes directly into audited codebases litters external repositories.
  • Lack of persistent knowledge accumulation: Once a transient chat session ends, research findings and comparative matrices vanish, preventing incremental tracking and baseline reviews.

This guide demonstrates how to combine Holon's Research Steward template with the Multi-Workspace Attach mechanism to build a long-lived technical research agent named ecosystem-researcher.

In this system:

  • Out-of-the-box template: Agents created from the research template come pre-equipped with necessary technical research skills; no manual skill wiring is needed.
  • Autonomous maintenance and attachment: You do not need to clone repositories in advance. Instruct the agent to clone and attach repositories automatically. The agent maintains its private knowledge base without requiring manual directory creation or config editing.
  • Concise prompt interactions: Code citation standards, fact-versus-inference boundaries, and report filing paths are permanently codified in the agent contract (AGENTS.md). Daily prompts can be brief and natural.
  • Everyday mobile workflows: Forward open-source project links or technical documents from mobile or desktop devices. The agent performs in-depth research asynchronously in the background. Click artifact links in the brief to view the findings.

Core mental model

Understand these core design principles before starting:

  1. Role contract and evidence discipline: A research agent's primary mission is evidence gathering and objective decision briefing, not unauthorized code modification or autonomous business decisions. Reusing the research-steward template establishes strict evidence standards:

    • Distinguish facts (supported by verified commit SHAs, line numbers, or official documentation), inferences (architectural conclusions drawn from evidence), and recommendations (actionable advice for internal systems).
    • Prioritize primary sources over unverified web summaries.
    • Treat conclusions as valid specifically for the baseline commit; record updates incrementally rather than rewriting historical evaluations.

  2. Autonomous maintenance and underlying architecture: You do not need to act as a file manager. The agent initializes directory structures, populates project registries, and archives comparative reports autonomously based on high-level goals and shared links. Understanding the underlying file layout explains how the agent sustains long-term memory across sessions.

  3. Agent Home decoupled from external workspaces:

    • agent_home: The agent's private, dedicated workspace storing its long-term knowledge base, registry (registry.yaml), taxonomy (taxonomy.md), and historical deliverables.
    • Attached external workspaces: Multiple external open-source repositories attached into the runtime. The agent switches execution roots to inspect source code without writing research notes or temporary files into external repositories.

  4. Multi-client access and asynchronous execution: Powered by Holon's background daemon and WorkItem scheduling, research runs asynchronously. You can share a GitHub link from a mobile device and lock your screen; the agent fetches, analyzes, and compares in the background, delivering a structured brief when complete.

Before you start

  • A running Holon daemon (Web GUI accessible at http://localhost:8080, terminal CLI holon available).
  • No need to pre-clone target repositories: You can provide repository URLs directly to the agent to clone and attach, or point to existing local project directories.

Steps

1. Create an agent from the research template

Holon provides the research-steward template designed for deep technical research with strict evidence rules.

Built-in skills: The research-steward template preconfigures essential research skills upon creation (such as ghx for GitHub data retrieval, sview for structured read-only code review, and writing-clearly-and-concisely for disciplined briefings). The agent is ready to work immediately; you do not need to manually configure or enable these skills.

Option A: Using the Web GUI

  1. Open the Web GUI: Navigate to Holon Web GUI in your browser (default http://localhost:8080).
  2. Create the Agent:
    • Click Templates (/templates) in the left navigation menu.
    • Locate research-steward in the template list.
    • Click Create Agent and fill in the form:
      • Agent ID: ecosystem-researcher
      • Name: Ecosystem Researcher
    • Confirm creation.

Option B: Using the CLI

Run a single command in your terminal:

holon agent create ecosystem-researcher --template research-steward --name "Ecosystem Researcher"

The agent's root contract (~/.holon/agents/ecosystem-researcher/AGENTS.md) is loaded with the role contract and evidence guidelines.

2. Attach multiple open-source project workspaces

To inspect local source code across multiple repositories, attach target projects into the agent's workspace bindings.

The simplest approach is to ask the agent directly in the conversation prompt:

"Clone https://github.com/org/project-a and https://github.com/org/project-b locally and attach them as your workspaces."

The agent pulls the repositories into local paths and issues internal workspace attach calls automatically.

Option B: Attach existing local directories via CLI

If you have already cloned the target repositories locally, attach them using the CLI:

holon workspace attach --agent ecosystem-researcher /path/to/project-a
holon workspace attach --agent ecosystem-researcher /path/to/project-b

Verify attached workspaces:

holon agent get ecosystem-researcher

The attached_workspaces field lists all associated external paths.

Note: Attaching a workspace grants read and execution authority over that directory without changing the agent's default home root. Daily operations remain centered in the agent's private agent_home.

3. Under the hood: Autonomous knowledge base architecture

Autonomous operation: In everyday use, you do not need to create these directories or edit YAML files manually. When assigned research goals or links, the agent initializes the directory structure, updates project indices, and archives reports autonomously according to its contract. This section outlines the internal file structure to explain how the agent maintains durable long-term memory.

Inside agent_home, the agent automatically organizes and maintains this layout:

~/.holon/agents/ecosystem-researcher/
├── AGENTS.md                  # Durable role contract and evidence guidelines
├── work/agent-ecosystem/      # Core research knowledge base (maintained by agent)
│   ├── taxonomy.md            # Ecosystem categorization (evolving taxonomy)
│   ├── registry.yaml          # Unique project registry and status tracking
│   ├── projects/              # Per-project long-term analysis archives
│   │   ├── project-a/
│   │   │   ├── metadata.yaml  # Source path, baseline commit, repository metadata
│   │   │   ├── architecture.md# Architecture breakdown and core module evidence
│   │   │   └── updates.md     # Incremental release logs (append-only)
│   │   └── project-b/
│   └── matrices/              # Cross-project comparative matrices

Project registry specification (registry.yaml)

When discovering a new target, the agent creates and updates entries in registry.yaml:

meta:
  initialized: 2026-10-29
  description: "AI Agent ecosystem tracked project registry"

objects:
  - slug: project-a
    name: "Project A Runtime"
    category: "agent_runtime"
    status: "monitoring"
    upstream: "https://github.com/org/project-a"
    sources:
      - role: primary
        local_path: "/home/user/src/github.com/org/project-a"
        baseline_commit: "a1b2c3d4..."
    research_path: "projects/project-a"

  - slug: project-b
    name: "Project B Harness"
    category: "harness"
    status: "monitoring"
    upstream: "https://github.com/org/project-b"
    sources:
      - role: primary
        local_path: "/home/user/src/github.com/org/project-b"
        baseline_commit: "e5f6g7h8..."
    research_path: "projects/project-b"

By storing state in structured files, the agent recovers historical context even after model context rotation or session restarts.

4. Launch a cross-project architecture comparison

Dispatching tasks requires no repetitive formatting or citation instructions; rules are already preserved in AGENTS.md.

Example task prompt (sent directly in conversation):

"Investigate the differences between project-a and project-b regarding process scheduling and interruption recovery, and create a comparative matrix."

Autonomous agent execution loop:

  1. Switch execution roots for code inspection: The agent switches to project-a and project-b using internal tools, locating relevant abstractions with sview and recording exact line numbers and commit hashes.
  2. Archive comparative findings: The agent switches back to agent_home, writes findings into work/agent-ecosystem/matrices/task-resumption.md, and updates per-project architecture.md files.
  3. Deliver a concise brief: The agent returns a structured summary in the conversation with links to generated artifacts.

5. Inspect research deliverables and verify isolation

  1. Review findings: Once finished, the agent outputs an executive summary in the chat.

    • Click the deliverable links inside the completion brief, or open work/agent-ecosystem/matrices/task-resumption.md directly in the Web GUI left file explorer to review the complete matrix.

  2. Verify external repository purity: All notes, logs, and matrices reside strictly in agent_home. Verify that external repositories remain untouched:

    git -C /home/user/src/github.com/org/project-a status
git -C /home/user/src/github.com/org/project-b status

    Both output working tree clean. Research activity produces zero file pollution in observed repositories.

Technical discovery frequently happens outside desktop coding sessions—while reading technical news, social feeds, or community posts on mobile devices.

When discovering an interesting open-source repository or architecture document on your phone (via the iOS client, Android client, or mobile browser):

  1. Share or send the link to the Agent: Paste the link into the Holon conversation with a concise note:

    "Research this new runtime: https://github.com/example/novel-runtime . Focus on its scheduling model and how it compares to our observed projects."

  2. Asynchronous background execution:

    • Lock your screen or switch apps immediately. Holon runs as a persistent daemon with durable WorkItems; active client connections are not required.
    • The agent fetches the repository README, releases, and documentation using web and GitHub tools (WebFetch, WebSearch, ghx).
    • It records the entry in registry.yaml and produces an initial evaluation in projects/novel-runtime/architecture.md.

  3. Review deliverables anywhere:

    • Reopen your phone client or desktop Web GUI later. The evaluation is ready in your conversation feed, outlining positioning, architectural advantages, limitations, and ecosystem fit.
    • If the project warrants deep dive inspection, clone the repository locally upon returning to your workstation and attach it as a workspace. The agent continues from existing findings directly into AST-level code inspection.

Advanced: Incremental tracking and scheduled patrols

As open-source projects evolve, avoid repeating full-scale research on each release:

  • Baseline commit locking: Keep evaluations pinned to baseline_commit recorded in registry.yaml. Compare changes only when intentionally bumping baselines.
  • Configure scheduled patrols: Use Holon's timer mechanism (see Schedule agent work) to configure weekly or daily automated wakeups in the Web GUI or CLI. The agent checks for upstream releases or commits, recording breaking changes into updates.md to maintain an active technical radar.