A tiny coding agent you can read in 10 minutes.
No installs. No dependencies. Just Python.

---

What is cobalt?

Cobalt lives in your terminal. You type what you want, and it does it - reads files, writes code, runs commands. It talks to an LLM behind the scenes and carries out whatever the model asks it to do.

It's built around the same idea as this article: an AI coding agent is just a loop that sends your message to a model, runs whatever tools the model asks for, and feeds the results back. That's the whole trick.

You type something
    ↓
Model thinks and picks a tool
    ↓
Cobalt runs the tool on your machine (read a file, run a command, edit code…)
    ↓
Result goes back to the model
    ↓
Model reads the result and either calls another tool or answers you

Features

• 4 tools - read files, list directories, edit files, run shell commands
• Zero dependencies - nothing to pip install, just the Python standard library
• Works everywhere - tested on i686 (32-bit), x86_64, ARM, ARM64, Windows, Linux
• Works with any OpenAI-compatible API - Z.AI, OpenAI, Ollama, vLLM, LM Studio, anything
• Smart about long chats - auto-trims old messages so the API doesn't time out
• Won't go crazy - caps on how many tool calls it makes per turn and per session

Quick Start

# Clone the repo
git clone https://github.com/Master290/cobalt.git
cd cobalt

# Set your API key (or put it in a .env file)
export OPENAI_API_KEY=sk-xxxx          # OpenAI
export ZAI_API_KEY=xxx                 # Z.AI
# Any key variable works - cobalt checks OPENAI_API_KEY first, then ZAI_API_KEY

# Point it at any OpenAI-compatible endpoint (optional - has sensible defaults)
export OPENAI_BASE_URL=http://localhost:11434/v1   # Ollama
export OPENAI_BASE_URL=https://api.openai.com/v1   # OpenAI
export ZAI_BASE_URL=https://api.z.ai/api/coding/paas/v4  # Z.AI Coding Plan

# Pick a model (optional)
export OPENAI_MODEL=gpt-4o
export ZAI_MODEL=glm-5.2

# Run it
python3 cobalt.py

That's it.

Configuration

Everything is optional. Set via environment variables or put them in a .env file.

Variable	Default	What it does
OPENAI_API_KEY		Your API key (checked first)
ZAI_API_KEY		Your API key (fallback)
OPENAI_BASE_URL	https://api.openai.com/v1	API endpoint (checked first)
ZAI_BASE_URL	https://api.z.ai/api/coding/paas/v4	API endpoint (fallback)
OPENAI_MODEL	gpt-4o	Model name (checked first)
ZAI_MODEL	glm-5-turbo	Model name (fallback)
COBALT_MAX_TOKENS	4096	Max tokens per response
COBALT_MAX_TOOL_ROUNDS	25	Max tool rounds per user message
COBALT_MAX_TOOLS_PER_RESPONSE	5	Max tool calls in one model response
COBALT_MAX_CONTEXT_CHARS	60000	Trims old messages above this size
COBALT_NO_COLOR		Set to 1 to turn off colors

OPENAI_* variables win over ZAI_*. This means you can switch providers just by changing one or two env vars.

Examples

With OpenAI

export OPENAI_API_KEY=sk-xxxx
python3 cobalt.py

With Z.AI

export ZAI_API_KEY=your_key
python3 cobalt.py

Example Session

============================================================
 cobalt  |  model: glm-5-turbo  |  endpoint: https://api.z.ai/api/coding/paas/v4
 Ctrl+C to exit.  Type your task below.
============================================================
You: create hello.py with a hello world function

  -> edit_file({"path": "hello.py", "old_str": "", "new_str": "def hello(): ..."})
     {"path": "/home/user/hello.py", "action": "created_file"}

cobalt: Done! Created hello.py with a hello() function.

You: add a multiply function

  -> read_file({"filename": "hello.py"})
     {"file_path": "/home/user/hello.py", "content": "def hello(): ..."}

  -> edit_file({"path": "hello.py", "old_str": "def hello():", "new_str": "..."})

cobalt: Added multiply(a, b) to hello.py.

You: run it

  -> run_command({"command": "python3 hello.py"})
     {"exit_code": 0, "stdout": "Hello World\n", "stderr": ""}

cobalt: Output: Hello World

How It Works (in plain English)

1. You type a request
2. Cobalt sends it to the LLM along with a list of tools it can use
3. The LLM responds with either:
   • A normal text answer, or
   • A tool call like tool: run_command({"command": "ls"})
4. If it called a tool, cobalt runs it on your machine and sends the result back
5. The LLM reads the result and decides: call another tool, or answer the user
6. When the LLM finally answers in plain text, cobalt prints it and waits for your next input

That loop - message → tool call → result → repeat — is all there is.

Requirements

• Python 3.7 or newer
• Any CPU architecture (32-bit or 64-bit)
• Any OS (Linux, Windows, macOS, BSD)
• An API key for an OpenAI-compatible LLM (or a local one like Ollama)

License

MIT