Content
# LoopBack: An Agentic Loop for Your Terminal or Web App
LoopBack is a powerful, terminal/web-based agentic loop that enables intelligent agents (like Claude or Gemini) to interact with your system. It leverages **Docker-isolated execution** for secure code execution and introduces **skills**, pre-authored Markdown playbooks, to extend the agent's capabilities without modifying its core code.
## Features
* **Streaming Agentic Loop:** Enables real-time interaction and tool execution as the agent processes information.
* **Secure Docker-Isolated Execution:** Your code runs safely in a disposable Python 3.12 container, protecting your host system.
* **Extensible with Skills:** Easily teach the agent new procedures by adding `SKILL.md` playbooks, allowing for dynamic capability expansion.
* **Organize with Plugins:** Group related skills into plugins for better organization and modularity (`external/<plugin>/skills/<name>/SKILL.md`).
* **Flexible User Interfaces:** Choose between a rich terminal experience or a modern web-based UI (similar to Claude/Gemini).
* **Robustness with Retry Mechanism:** Transient API errors are automatically retried with exponential backoff for increased reliability.
## Built-in Tools
All tools that interact with the system are sandboxed into the Docker container (`/app`), ensuring your host file system is isolated.
* **ToolRunBash:** Executes a bash command in the Docker container (e.g., `ls -l`, `pip install`).
* **ToolReadFile:** Reads a file from the Docker container.
* **ToolGlobFiles:** Finds matching file paths in the Docker container.
* **ToolGrep:** Searches for text matches within files in the Docker container.
* **ToolWriteFile:** Safely writes content to a file in the Docker container.
* **ToolEditFile:** Edits a string within a file in the Docker container.
* **ToolWebFetch:** Fetches the plain text content of a web URL from within the Docker container.
* **ToolWebResearch:** Performs a web search using DuckDuckGo to gather information for research tasks.
## Quick Start
### Prerequisites
* Python 3.11+
* [Docker Desktop](https://www.docker.com/products/docker-desktop/) running
* An Anthropic or Gemini API key (essential for agent functionality)
### Install & Run
```bash
uv sync # Installs dependencies with `uv`
cp .env.example .env # Copy the example environment file and add your API keys.
```
**Running the Terminal UI:**
```bash
uv run python simple_ui.py
# or: make client
```
At startup, the agent prints which skills were discovered under `external/`. Type a request and watch the loop work; `quit`, `exit`, or `q` to leave.
**Running the Web UI:**
```bash
uv run python -u web_ui/server.py
# or: make web
```
Then open [http://localhost:8000](http://localhost:8000) in your browser. This starts both the static resource server and a bi-directional streaming WebSocket server on port `8765`.
## Adding Skills
A **skill** is a playbook containing instructions for the agent. Skills empower LoopBack to perform complex tasks by providing step-by-step instructions, allowing you to teach the agent new procedures without changing code. Skills are discovered automatically from the `external/` directory.
To add a new skill:
1. Create a directory under `external/` (e.g., `external/my-skill/`).
2. Inside that directory, create a `SKILL.md` file.
3. Add YAML frontmatter and your instructions.
**Example `external/my-skill/SKILL.md`:**
```markdown
---
name: my-skill
description: Use this skill when you need to perform my custom procedure.
---
# My Custom Skill
1. Run this specific command.
2. Ensure the output matches this format.
```
## MCP Servers
LoopBack can integrate with external tools and services using the **Model Context Protocol (MCP)**, a standardized way for agents to communicate with external resources. You can configure MCP servers by creating an `mcp_servers.json` file in the project root. LoopBack will automatically connect to these servers at startup and make their tools available to the agent.
### Standard I/O
For MCP servers that communicate over stdin/stdout, configure them using `command` and `args`:
```json
{
"mcpServers": {
"sqlite": {
"command": "uvx",
"args": ["mcp-server-sqlite", "--db-path", "~/test.db"]
}
}
}
```
### SSE URL Connection
For MCP servers that provide HTTP/SSE endpoints, configure them using the `url` property:
```json
{
"mcpServers": {
"my-remote-server": {
"url": "http://localhost:8080/sse"
}
}
}
```
## Documentation
* [docs/architecture.md](docs/architecture.md) — how the loop, events, and message flow fit together.
* [docs/skills.md](docs/skills.md) — authoring SKILL.md, plugin layout, examples.
* [docs/tools.md](docs/tools.md) — the built-in tools and how to add your own.
## Development
To contribute or develop with LoopBack, use these commands:
```bash
uv sync --extra dev # pytest, ruff, mypy
uv run pytest
uv run ruff format . && uv run ruff check . --fix
uv run mypy .
```
## License
MIT — see [LICENSE](LICENSE).
