toolloop

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 18 Open GitHub ↗

Multi-LLM agent framework with Claude Code-like tools. Use DeepSeek, Claude, GPT, Llama, or any model — same tools, same skills, swap freely. Includes file editing, code search, shell execution, sub-agents, and a production-ready API. The missing SDK between your LLM and your codebase.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ToolLoop

**Multi-LLM agent framework with built-in tools for any model.**

ToolLoop gives you agentic coding capabilities — file editing, code search, shell execution, sub-agents, skills — while letting you swap LLMs freely. Use DeepSeek for cheap tasks, Claude for complex ones, GPT for everything in between. Same tools, same prompt, different brains.

![ToolLoop Demo](https://raw.githubusercontent.com/zhiheng-huang/toolloop/main/demo.gif)

## 10-Line Demo

```python
from sdk import query, ToolLoopOptions

async for event in query(
    prompt="Find all TODO comments in this repo, fix them, then run the tests",
    options=ToolLoopOptions(
        model="bedrock/converse/deepseek.v3.2",  # or any LLM
        allowed_tools=["Read", "Edit", "Grep", "Glob", "Bash"],
        workdir=".",
    ),
):
    print(event)
```

## Why ToolLoop?

Most agentic coding tools such as Claude Code are locked to a single LLM provider. ToolLoop breaks that lock.

### Core Value Propositions

**1. Multi-LLM with Smart Model Routing**
Use DeepSeek V3.2 ($0.62/M tokens) for file search and simple tasks, Claude ($3/M) only when you need it. Switch models mid-conversation — start cheap, escalate to powerful. Same tools, same skills, 5x cheaper on routine work.

**2. Customizable Reasoning**
You control every tool implementation and the agent loop itself. Modify how Edit works, add domain-specific tools, change the orchestration logic. Most agentic tools are closed-source black boxes.

**3. Production Deployable SDK**
Most agentic coding tools are CLIs for developers. ToolLoop is an API you ship to customers — FastAPI + WebSocket + Docker sandbox + multi-tenant session isolation, ready for production. Or embed it in your product with 10 lines of Python.

**4. Skills Portability**
Load skills from the SKILL.md ecosystem. Community skills work instantly across DeepSeek, GPT, Llama, Gemini, and Claude. Skills aren't locked to one vendor.

**5. No Vendor Lock-in**
If a provider has an outage, rate-limits you, or raises prices — switch models with one config change. Spread load across providers for resilience.

**6. Cost Observability**
Per-model, per-turn cost tracking with input/output token breakdown. Know exactly what each agent task costs before you scale it.

```python
elif isinstance(event, ResultMessage):
    print(f"{event.turns} turns | {event.input_tokens:,} in + {event.output_tokens:,} out | ${event.total_cost:.4f}")
```

**7. Simple, Hackable Codebase**
The entire framework is ~2,700 lines of Python. The agent loop is ~250 lines. No layers of abstraction, no plugin systems to learn — read it, understand it, change it in an afternoon. Compare that to LangChain's 100K+ lines.

**8. Open Source**
Fork it, extend it, self-host it. No usage fees, no telemetry, no approval needed.

### Comparison

|  | ToolLoop | Proprietary Agent CLIs | LangChain |
|---|---|---|---|
| Any LLM | **Yes** | Single provider | Yes (complex) |
| File/code tools built-in | **Yes** | Yes | No |
| Skills ecosystem | **SKILL.md compatible** | Varies | No |
| Model switching mid-session | **Yes** | No | Manual |
| Production API + WebSocket | **Yes** | No | DIY |
| Container sandbox | **Yes** | No | No |
| Cost tracking per turn | **Yes** | No | No |
| Codebase size | **~2,700 lines** | Closed source | 100K+ lines |
| Open source | **Yes** | No | Yes |

## Quick Start

### Install

```bash
git clone https://github.com/zhiheng-huang/toolloop.git
cd toolloop
pip install -e ".[dev]"
```

### Configure

Create a `.env` file:

```bash
# AWS Bedrock (primary — supports Claude, DeepSeek, Llama, Mistral)
TOOLLOOP_AWS_ACCESS_KEY_ID=your-key
TOOLLOOP_AWS_SECRET_ACCESS_KEY=your-secret
TOOLLOOP_AWS_REGION=us-west-2

# Default model
TOOLLOOP_DEFAULT_MODEL=bedrock/converse/deepseek.v3.2

# Optional: direct API keys for non-Bedrock models
TOOLLOOP_OPENAI_API_KEY=sk-...
TOOLLOOP_MOONSHOT_API_KEY=...
TOOLLOOP_DEEPSEEK_API_KEY=...
TOOLLOOP_GOOGLE_API_KEY=...
```

### Run the Interactive CLI

```bash
# Interactive chat
python -c "
import sys; sys.path.insert(0, '.')
import asyncio
from cli.chat import run_chat
asyncio.run(run_chat(workdir='.'))
"

# With extra skills from a project directory
python -c "
import sys; sys.path.insert(0, '.')
import asyncio
from cli.chat import run_chat
asyncio.run(run_chat(workdir='.', command_dirs=['/path/to/project/.claude']))
"
```

### Start the API Server

```bash
python -c "import sys; sys.path.insert(0, '.'); from api.server import serve; serve()"
```

Then hit the endpoints:

```bash
# Health check
curl http://localhost:8100/api/v1/health

# One-shot query
curl -X POST http://localhost:8100/api/v1/query \
  -H "Authorization: Bearer your-key" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is 2+2? Answer briefly.", "max_turns": 2}'

# Interactive docs
open http://localhost:8100/docs
```

## Demos

### One Skill, Three Models

Runs the same task on DeepSeek, Claude, and GPT — shows cost and performance differences:

```bash
python examples/demo_three_models.py
```

Output:

```
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Model              ┃ Tools  ┃ Turns  ┃  Input Tok ┃ Output Tok ┃       Cost ┃     Time ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ DeepSeek V3.2      │   4    │   5    │      8,412 │      1,203 │    $0.0074 │     9.3s │
│ Claude Sonnet 4.6  │   4    │   3    │      6,891 │        892 │    $0.0340 │     8.8s │
│ GPT-5.4            │   3    │   2    │      5,230 │        645 │    $0.0228 │     8.9s │
└────────────────────┴────────┴────────┴────────────┴────────────┴────────────┴──────────┘
```

### Hero 10 Lines

```bash
python examples/hero_10_lines.py
```

### Scripted Multi-Turn Demo

Two-turn demo with model switching (DeepSeek -> Claude), with typing effects for screen recording:

```bash
python examples/demo_scripted.py

# Record with asciinema:
asciinema rec demo.cast -c "python examples/demo_scripted.py"
```

## SDK

### One-shot query

```python
from sdk import query, ToolLoopOptions
from core.messages import AssistantMessage, ToolResultMessage, ResultMessage

async for event in query(
    prompt="Fix the bug in auth.py, then run tests",
    options=ToolLoopOptions(
        model="bedrock/converse/deepseek.v3.2",
        allowed_tools=["Read", "Edit", "Bash", "Grep", "Glob"],
        workdir="/path/to/project",
    ),
):
    if isinstance(event, AssistantMessage) and event.text:
        print(event.text)
    elif isinstance(event, ToolResultMessage):
        print(f"  [{event.tool_name}] {'ok' if not event.error else event.error}")
    elif isinstance(event, ResultMessage):
        print(f"Done: {event.turns} turns, ${event.total_cost:.4f}")
```

### Switch models mid-conversation

```python
from sdk import query, ToolLoopOptions

# Start cheap with DeepSeek
async for event in query(
    prompt="What does auth.py do?",
    options=ToolLoopOptions(model="bedrock/converse/deepseek.v3.2"),
):
    print(event)

# Upgrade to Claude for the hard part
async for event in query(
    prompt="Now refactor the auth middleware with proper error handling",
    options=ToolLoopOptions(model="bedrock/converse/us.anthropic.claude-sonnet-4-6"),
):
    print(event)
```

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/health` | Health check |
| POST | `/api/v1/query` | One-shot agent query |
| POST | `/api/v1/sessions` | Create a session |
| GET | `/api/v1/sessions` | List user sessions |
| GET | `/api/v1/sessions/{id}` | Get session |
| DELETE | `/api/v1/sessions/{id}` | Destroy session |
| POST | `/api/v1/sessions/{id}/query` | Multi-turn query |
| WS | `/api/v1/ws` | Streaming WebSocket |

### WebSocket Protocol

```bash
# Connect with auth
websocat "ws://localhost:8100/api/v1/ws?token=your-key"

# Send queries
{"type": "query", "prompt": "List files in current directory"}

# Multi-turn (reuse session)
{"type": "query", "prompt": "Now read the first file", "session_id": "abc-123"}
```

## Tools (11)

| Tool | Description | Read-only? |
|------|-------------|-----------|
| **Read** | Read files (text, PDF, images) with line ranges | Yes |
| **Write** | Create or overwrite files | No |
| **Edit** | Exact string replacement with uniqueness check | No |
| **Glob** | Find files by glob pattern | Yes |
| **Grep** | Regex content search (ripgrep or grep fallback) | Yes |
| **Bash** | Shell execution with timeout | No |
| **WebFetch** | Fetch and extract content from URLs | Yes |
| **WebSearch** | Web search via Tavily API | Yes |
| **Agent** | Spawn sub-agents for complex subtasks | No |
| **AskUser** | Ask the user a question | Yes |
| **Skill** | Invoke a loaded skill by name | No |

Read-only tools run in parallel. Mutating tools run serially.

## Skills

ToolLoop loads skills from three sources:

1. `~/.toolloop/skills/*/SKILL.md` — user-wide
2. `.toolloop/skills/*/SKILL.md` — per-project
3. `~/.claude/skills/*/SKILL.md` — community skills

It also loads plain markdown **commands** and **agents** from any `.claude` directory:

```bash
# Load commands/agents from a project
python -c "
import sys; sys.path.insert(0, '.')
import asyncio
from cli.chat import run_chat
asyncio.run(run_chat(
    workdir='/path/to/project',
    command_dirs=['/path/to/project/.claude']
))
"
```

Commands become `cmd:name` skills, agents become `agent:name` skills.

### Example: Running a Skill

With skills loaded, use them in the interactive CLI:

```
You > Use the seo skill to audit https://example.com

> Tool: Skill(skill=seo)
    [skill:seo] Tool: WebFetch(url=https://example.com)
    [skill:seo] Tool: Grep(pattern=<meta, path=.)
    [skill:seo] Tool: Read(file_path=index.html)
    [skill:seo] Done: 4 turns, 6,820 tokens

> Result: ## SEO Audit
  > - Missing meta description
  > - H1 tag present but not keyword-optimized
  > - No structured data (JSON-LD) found
  > - Images missing alt attributes (3 found)
```

Or via the SDK:

```python
from sdk import query, ToolLoopOptions

async for event in query(
    prompt="Use the seo skill to audit https://example.com",
    options=ToolLoopOptions(model="bedrock/converse/deepseek.v3.2"),
):
    print(event)
```

## Architecture

```
toolloop/
├── core/
│   ├── loop.py           # Agent loop: prompt -> LLM -> tools -> loop
│   ├── llm_router.py     # LiteLLM + Bedrock routing
│   └── messages.py       # Event types
├── tools/                # 11 tool implementations
├── sandbox/
│   ├── local.py          # Direct filesystem (CLI)
│   ├── docker.py         # Isolated container (production)
│   └── secure.py         # Path validation wrapper
├── sdk/                  # query(), ToolLoopOptions
├── cli/                  # Interactive chat + one-shot run
├── api/                  # FastAPI + WebSocket server
├── skills/               # SKILL.md loader
└── config/               # Pydantic settings
```

## Model Pricing Reference

| Model | Input / 1M tokens | Output / 1M tokens | Provider |
|-------|-------------------|---------------------|----------|
| DeepSeek V3.2 | $0.62 | $1.85 | AWS Bedrock |
| Claude Sonnet 4.6 | $3.00 | $15.00 | AWS Bedrock |
| GPT-5.4 | $2.50 | $15.00 | OpenAI API |

## License

MIT

toolloop

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README