AgentLoom

Install

The source installer is the recommended starting point. It prepares the TUI, the Python runtime, and their dependencies together, so you do not need to build environments by hand.

git clone https://github.com/linora-u/AgentLoom.git
cd AgentLoom
./install

Open a new terminal after installation, then verify the command from the repository root:

agentloom --version
agentloom --snapshot

The installer:

• installs missing uv and Bun with their official installers;
• creates a locked Python environment under ~/.agentloom/venv;
• builds the current-platform TypeScript/OpenTUI binary;
• installs agentloom and agentloom-tui under ~/.agentloom/bin;
• adds that directory to your shell PATH when a writable shell config exists.

The source installer currently targets macOS and Linux shells. It requires Git and Bash; curl is required only when uv or Bun must be installed.

Rerun ./install to update from source. Once installed, agentloom update rebuilds from the recorded trusted checkout. --no-modify-path is only an optional switch that leaves shell configuration unchanged; it is not an update requirement.

The installed TUI checks that trusted checkout in the background. If relevant source files are newer than the installed compatible unit, Ctrl+X offers an explicit whole-product update and safe restart. It never pulls Git or replaces an active Session silently.

Use a custom install location or leave PATH unchanged when needed:

AGENTLOOM_INSTALL_DIR="$HOME/tools/agentloom" ./install
./install --no-modify-path

Configure Application models

Copy the model template before using TUI chat or running an Agent:

cp config/llm.example.yaml config/llm.yaml

Edit config/llm.yaml and replace the placeholders. Do not commit this file; it is ignored because it contains credentials.

model:
  default_model_type: powerful
  powerful:
    model: "openai/<model-id>"
    api_key: "<api-key>"
    base_url: "https://<openai-compatible-endpoint>"  # optional for OpenAI
    tool_choice: "auto"

This file is the single model configuration source for both runtimes. Application Agents resolve it through Python and their YAML model_type; the TypeScript Studio adapter maps the same profiles, endpoints, credentials, and compatible request options into the bundled Studio runtime. /models and Ctrl+X select a Studio profile from config/llm.yaml without changing any Application's model_type. Studio startup fails clearly instead of falling back to an unconfigured ambient model when this configuration is missing or invalid.

Start with the TUI

Run agentloom inside the project you want to inspect, or pass the project explicitly:

cd /path/to/AgentLoom
agentloom

# Inspect another AgentLoom project
agentloom --project /path/to/project

The TUI is an Applications-first control plane. Its independent Studio Agent can inspect the whole project, directly edit the selected Application, show Tool and Diff blocks, validate configuration, request permission to run it, inspect structured evidence, and continue repairing failures.

1. Create or select an Application

Press Enter to send a request. A useful first prompt states the application, roles, inputs, outputs, and acceptance criteria:

Create an Application named release_review.
Use one Supervisor and two Workers for API review and test review.
Choose model types from config/llm.yaml.
Validate it and ask before the first real Run.

The Studio edits files directly in the selected scope and shows the resulting Diff. It loops through Effective Config, YAML/reference validation, an approved smoke Run, and structured Run evidence. If real execution is not approved it must report “configuration validated, not run” rather than claiming completion. Large model-facing Application detail is deduplicated and paginated at ten Agents per call. Studio persists Session status, retry, permission, question, and Task sub-session events; quiet model latency is not treated as a cancellation signal. Esc remains the explicit manual interrupt.

2. Understand the workspace numbers

The homepage counts directories under applications/, not every expanded Supervisor and Worker YAML. Global Skills counts root runtime Skills; an Application's private Skills appear when that Application or Agent is opened. Use Ctrl+X to search Applications, main Supervisor Agents, Skills, Schedules, Runs, permissions, models, and commands. Worker Agents remain inside their Application and main-Agent details instead of appearing as independent global-search entries.

Application detail shows Effective Config and source attribution for Agent topology, model type, Tools, Skills, permissions, Hooks, MCP, workflow files, validation, Working Revision, and Running Revision. Run detail defaults to an actionable summary rather than raw Events.

3. Permissions and revisions

Application Only is the default. Reads are project-wide, direct writes are limited to the current Application, and Studio asks for Shell, global, other Application, or new-path access. Choose 1 once, 2 for this Session, or 3 reject. Full Access is one on/off toggle in Ctrl+X: it can be preset before selecting an Application and remains active while switching Applications; it resets on exit. Switching Applications keeps the current Studio memory, while /new starts a fresh Session. /compact compresses the current Session with the selected Studio model while preserving task continuity, durable history, and completed file changes; the Runtime also reports automatic compaction when the context approaches its limit. Switching is blocked during an active Agent Loop; wait or press Esc first. Sub-agent execution text remains visible until the next turn; select TUI text and press Ctrl+Y to copy it. When the Agent needs a business decision, choose a visible option or type an answer; separate multiple answers with |.

Each Run pins an application_revision in its manifest. Later edits change the Working Revision but do not hot-switch a running Agent.

See agentloom-tui/README.md for TUI architecture and contributor details.

5. Run schedules explicitly

The TUI can create and manage durable schedules. Automatic firing is a separate foreground service, so closing the TUI never leaves a hidden daemon behind.

agentloom schedules --project /path/to/project serve

Scheduled YAML can enable Goal Mode, but unattended Goals should set a token_budget; an omitted budget is intentionally unlimited. Budget exhaustion is recorded as the resumable budget_limited schedule status, not as an ordinary execution failure.

Run an existing Agent

To verify the framework without creating a new application, run the included code review example:

uv run loom run applications/ai_quality_analysis/workflows/code_review_agent.yaml

One run creates a receipt under .agentloom/runs/<application_id>/<run_id>/. When checkpointing is enabled, resumable task state lives under .agentloom/checkpoints/<application_id>/<task_id>/.

run_id identifies one attempt and changes after resume. task_id identifies the logical task and remains stable.

For work that must continue beyond one final answer or max_steps segment, a top-level Supervisor can enable Goal Mode. Only the root Supervisor can complete the Goal; Worker token usage is included in the same optional soft budget:

goal:
  enabled: true
  token_budget: 120000  # omit for unlimited

An active Goal continues on the same runtime and memory. budget_limited keeps its checkpoint and can resume after the budget is raised or removed. See Goal Mode.

How AgentLoom works

AgentLoom treats a multi-agent system as an application, not a loose collection of prompts.

This keeps orc