Index / agent

Tadpole

Category: AI Agents
Rank: No. 1656Tools index
Pricing: Open Source
Type: AGENT
Use case: Agent Building · Models: Train & Run · Research & Education
Interfaces: CLI
GitHub: 9 stars
Date: Published Oct 31, 2026

About

Tadpole is a tool-using LLM agent written in about 3,500 lines of plain Python with no agent framework. It handles files, shell, web search and fetch, sessions and compaction, and runs in a terminal or as a Telegram bot on a local 4B model or any OpenAI-compatible API. The repository also documents each build stage with tests and measurements, through SFT, expert iteration and a GRPO pilot, reporting Qwen3-4B pass@1 rising from 0.419 to 0.774 on untrained task types.

At a glance

Tadpole is a tool-using LLM agent written in about 3,500 lines of plain Python with no agent framework, plus a stage-by-stage record of how it was built and post-trained. You chat with it in a terminal or through a Telegram bot, and it can read and edit files, run shell commands, search and fetch the web, and compact long sessions. It runs on any OpenAI-compatible API or a local Qwen3-4B model. Tool calls run as soon as the model issues them, with no approval step. Its stronger case is as a study project: it is most worth your time if you want to see how an agent loop and its post-training work end to end.

Good fit

Developers who want to learn agent internals by reading small, tested code: the first tool-calling loop, sessions and traces, context budgeting, then a generated benchmark, SFT, expert iteration and a GRPO pilot. It also suits someone who wants a personal always-on Telegram agent they fully control and can modify.

Consider something else when

Skip it if you want a polished assistant with memory, plugins or MCP support today: cross-session memory, skills and MCP are listed on the roadmap, not shipped. Also skip it if you need to approve commands before they run, or cannot give it a disposable machine or account, since it executes shell commands and file writes without asking.

Start here

With Python 3.11 or later, clone the repo, create a venv and run pip install -e .. Export AGENT_BASE_URL, AGENT_MODEL and AGENT_API_KEY for your provider, then run python -m agent_from_scratch.agent and ask a question. To study the build instead, open the walkthrough notebook, which has saved outputs and reads on GitHub.

Cost and requirements

The code is MIT licensed; the Hugging Face adapters are Apache-2.0. Everyday use needs an API key from a provider such as DeepSeek, OpenAI or OpenRouter, billed by that provider, or a local model through Ollama or llama.cpp. The in-process llama.cpp path is macOS only, and the shell tool requires a POSIX system. Reproducing the post-training needs a 24 GB CUDA GPU; the author reports the whole training line cost about $140 on RunPod.

Limits to know

There is no confirmation prompt and no sandbox. The agent loop passes each tool call straight to the tool, and the shell tool runs any command through /bin/sh with your user's permissions and a copy of your environment variables, so a command can read an exported API key. Its working directory setting is described in the code as not a sandbox; the only guards are a timeout and an output size cap. The file tools accept absolute and home-directory paths; an optional workspace restriction exists, which the code says is not an OS sandbox. The Telegram bot answers one allowed user ID, but anyone holding the token controls it. The post-training gains (Qwen3-4B rising from 0.419 to 0.774 pass@1 on unseen task types) come from one training run per model on a small local benchmark, which the author says is not a claim about general agent ability.

Sources checked 2026-10-31. Source-based assessment.

Tech Stack

Python

Media

Comments (0)

No comments yet

Editorially curated, with community endorsements as a secondary signal. Corrections welcome.