_ ___ ___ ____ _ _ | | / _ \ / _ \ | _ \ / \ | | | | | | | || | | || |_) | / _ \ | | | |___ | |_| || |_| || __/ / ___ \ | |___ |_____| \___/ \___/ |_| /_/ \_\|_____|An agentic AI coding tool that lives in your terminal.
Built in Rust. Multi-model. Multi-agent. Extensible.
Part of AgentsMesh.ai
Click to watch the demo
Installation • Quick Start • Features • Distributed Cluster • Configuration • Architecture • License
Download pre-built binaries from Releases:
| Platform | Target |
|---|---|
| macOS (Apple Silicon) | aarch64-apple-darwin |
| Linux (x86_64) | x86_64-unknown-linux-gnu |
| Linux (ARM64) | aarch64-unknown-linux-gnu |
| Windows (x86_64) | x86_64-pc-windows-msvc |
git clone https://github.com/AgentsMesh/Loopal.git && cd Loopal
make install # builds optimized binary → ~/.local/bin/loopalRequires Bazel 8+ (via Bazelisk).
# Set your API key
export ANTHROPIC_API_KEY="sk-..." # or OPENAI_API_KEY, GOOGLE_API_KEY
# Start Loopal in your project
cd your-project && loopal
# Or pass a prompt directly
loopal "explain the architecture of this project"
# Server mode (no TUI, for CI/scripting)
loopal --server --ephemeral "run all tests and fix failures"Works out of the box with Anthropic, OpenAI, Google, and any OpenAI-compatible endpoint. Switch models on the fly with -m:
loopal -m claude-sonnet-4-20250514
loopal -m gpt-4o
loopal -m gemini-2.5-proSupports thinking/reasoning modes (auto, effort levels, token budgets) and per-task model routing.
Full-featured interactive TUI built with Ratatui:
- Markdown rendering with syntax highlighting
- Streaming responses with real-time progress
- Permission approval dialogs
- Multi-agent topology visualization
- Plan/Act mode toggle
- Slash-command completion
- Session resume (
loopal -r <session-id>)
| Category | Tools |
|---|---|
| File I/O | Read, Write, Edit, MultiEdit, ApplyPatch, CopyFile, MoveFile, Delete |
| Search | Grep (regex, context, file filters), Glob (pattern matching), Ls |
| Process | Bash (foreground + background), Fetch, WebSearch |
| Agent | AskUser, EnterPlanMode, ExitPlanMode, ListHubs |
All tools go through sandbox policy checks before execution.
Spawn sub-agents that run in parallel, communicate via message passing, and coordinate through a shared task store. The TUI provides a topology view to observe and interact with any agent in the tree.
First-class Model Context Protocol support:
- Stdio transport — spawn MCP servers as child processes
- Streamable HTTP transport — connect to remote MCP servers
- OAuth — automatic browser-based auth for protected servers
{
"mcp_servers": {
"my-server": {
"command": "npx",
"args": ["-y", "@my/mcp-server"]
}
}
}Run as an Agent Client Protocol server for IDE integration:
loopal --acp # JSON-RPC 2.0 over stdin/stdoutWorks with Zed, JetBrains, Neovim, and any ACP-compatible editor.
- Skills — Extend agent capabilities with project-specific markdown skill files (
/skill-nameinvocation) - Memory — Cross-session persistent memory that remembers observations and preferences
Three permission modes to control what the agent can do:
| Mode | Behavior |
|---|---|
bypass |
Auto-approve everything |
auto |
Smart approval based on intent classification |
supervised |
Require user confirmation for writes and commands |
Sandbox policies (strict/permissive/disabled) enforce filesystem, network, and command restrictions.
Run custom scripts on agent events — tool calls, session start, permission requests, etc:
{
"hooks": [
{
"event": "tool_call_post",
"tool_filter": ["Bash"],
"command": "notify-send 'Command executed'"
}
]
}Connect multiple Loopal instances into a cluster via MetaHub — a lightweight TCP coordinator that enables cross-hub agent communication.
# Terminal 1: Start MetaHub coordinator
loopal --meta-hub 0.0.0.0:9900
# Terminal 2: Connect first Hub
LOOPAL_META_HUB_TOKEN=<token> loopal --join-hub 127.0.0.1:9900 --hub-name code-hub
# Terminal 3: Connect second Hub
LOOPAL_META_HUB_TOKEN=<token> loopal --join-hub 127.0.0.1:9900 --hub-name review-hub- Discover hubs —
ListHubstool shows all connected hubs and their agents - Spawn remotely —
Agenttool withtarget_hubparameter creates agents on other hubs - Route messages —
SendMessageto"hub-name/agent-name"routes through MetaHub - Auto-relay — Permissions and events automatically propagate across hubs
| Dimension | Options | Controls |
|---|---|---|
| Frontend | --server / TUI (default) |
Who sees events and approves actions |
| Lifecycle | --ephemeral / persistent (default) |
Exit on idle vs. wait for next task |
| Cluster | --join-hub / standalone (default) |
Single instance vs. distributed |
All combinations are valid — a --server --join-hub instance is a headless cluster worker.
Loopal uses a layered config system — each layer overrides the previous:
~/.loopal/settings.json # Global settings
~/.loopal/LOOPAL.md # Global system prompt instructions
<project>/.loopal/settings.json # Project settings
<project>/.loopal/settings.local.json # Local overrides (gitignored)
<project>/LOOPAL.md # Project instructions
Key settings:
{
"model": "claude-sonnet-4-20250514",
"permission_mode": "supervised",
"thinking": { "type": "auto" },
"providers": {
"anthropic": { "api_key": "..." }
},
"mcp_servers": { },
"sandbox": { "policy": "strict" }
}Environment variables: ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY.
Loopal runs as a multi-process, Hub-centric system. Multiple Hubs can form a cluster via MetaHub.
┌───────────┐ ┌───────────┐ ┌───────────┐
│ TUI │ │ ACP (IDE) │ │ CLI │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
│ TCP (JSON-RPC 2.0) │
└───────────┬───────────────────┘
│
┌─────────────────────────────────────▼──────────────────────────────┐
│ Hub │
│ │
│ Registry ── agent parent/child tree + lifecycle tracking │
│ Dispatch ── broadcast events to all connected UI clients │
│ Relay ── race permission/question requests to UIs │
│ Spawner ── fork agent processes + bridge completion results │
│ │
│ stdio (JSON-RPC 2.0) │
│ ┌────────────┼────────────┐ │
│ │ │ │ │
│ ┌──────────▼──┐ ┌─────▼──────┐ ┌──▼───────────┐ │
│ │ Root Agent │ │ Sub-Agent │ │ Sub-Agent .. │ │
│ │ Kernel+LLM │ │ Kernel+LLM │ │ Kernel+LLM │ │
│ │ Tools+MCP │ │ Tools+MCP │ │ Tools+MCP │ │
│ └─────────────┘ └────────────┘ └───────────────┘ │
└────────────────────────────────────────────────────────────────────┘
┌──────────────┐
│ MetaHub │
│ (TCP coord) │
└──┬───────┬───┘
TCP │ │ TCP
┌────────────┘ └────────────┐
│ │
┌──────▼──────┐ ┌───────▼─────┐
│ Hub-A │ │ Hub-B │
│ (uplink) │ │ (uplink) │
│ ┌─────────┐ │ │ ┌─────────┐ │
│ │ Agent-1 │ │ ←── meta/route │ │ Agent-3 │ │
│ │ Agent-2 │ │ meta/spawn → │ │ Agent-4 │ │
│ └─────────┘ │ │ └─────────┘ │
└─────────────┘ └─────────────┘
How it works:
- Agents connect to Hub via stdio pipes (forked child processes). Each agent runs its own Kernel with LLM providers, tools, and MCP servers.
- UI clients (TUI, IDE via ACP, CLI) connect via TCP. Multiple clients can observe and interact with the same session simultaneously.
- Sub-agents are spawned on demand — Hub forks a new process, registers the parent/child relationship, and bridges completion results back to the parent as normal messages.
- MetaHub coordinates multiple Hubs via TCP. Cross-hub operations (routing, spawning, discovery) go through MetaHub transparently — agents don't know which Hub they're on.
- Events are broadcast to all UI clients. Permissions are raced to all connected UIs — first response wins. In cluster mode, permissions propagate through MetaHub.
- All communication uses JSON-RPC 2.0, whether over stdio or TCP.
Built as 40+ Rust crates in a layered architecture — see CLAUDE.md for the full dependency graph and development guide.
Usage: loopal [OPTIONS] [PROMPT]...
Arguments:
[PROMPT]... Initial prompt
Options:
-m, --model <MODEL> Model to use
-r, --resume <SESSION> Resume a previous session
-P, --permission <MODE> Permission mode (bypass/auto/supervised)
--plan Start in plan mode (read-only)
--server Run without TUI (server mode)
--ephemeral Exit after completing current task
--worktree Create isolated git worktree
--no-sandbox Disable sandbox enforcement
--acp Run as ACP server
--meta-hub <ADDR> Run as MetaHub cluster coordinator
--join-hub <ADDR> Join a MetaHub cluster
--hub-name <NAME> Hub name when joining a cluster
-h, --help Print help
Proprietary. Copyright (c) 2024-2026 AgentsMesh.ai. All Rights Reserved.
See LICENSE for full terms.