FirstCoder

A local Python coding agent built to make agent internals visible.

English · 简体中文

FirstCoder is a real, runnable local coding agent with a Textual TUI, tool calling, permissions, sessions, and context compaction. It is designed to be useful in daily work and easy to study in code.

If you want to understand how coding agents actually work, FirstCoder keeps the moving parts visible instead of hiding them behind a black box.

• Learn the agent loop, tool calling, permissions, sessions, and context handling.
• Build on a small Python codebase with clear module boundaries.
• Use a local coding agent while still being able to inspect how it works.

Why FirstCoder

Most coding-agent demos show the surface: a prompt goes in, code changes come out. FirstCoder focuses on the machinery in between.

Compared with larger projects like OpenCode, FirstCoder is intentionally smaller in scope.

The goal is not to out-feature a bigger coding agent. The goal is to keep the system real enough to use, but small enough that you can still read it end to end and understand why each subsystem exists.

That also makes FirstCoder a practical repo to study deeply, adapt for your own workflow, and turn into a resume-worthy or portfolio-friendly project after you have extended it.

Compared with more tutorial-first or lightweight learning repos, FirstCoder also tries to stay closer to a small but testable engineering system.

In this repo, the learning goal is important, but it is paired with enough runtime structure, tests, and a Harbor evaluation path to make the project useful after the first read-through.

It is built for people who want to:

• study how a coding agent is assembled
• modify or extend a local Python implementation
• understand the architecture well enough to explain it in an interview

Detailed subsystem design lives in the docs, not in this README.

Quickstart

Install with pipx:

pipx install firstcoder

Start the TUI:

firstcoder

Run one message without opening the TUI:

firstcoder --message "Summarize this repository in one paragraph"

Use line-oriented interactive mode:

firstcoder --interactive

What You Get

• Local Python coding agent
• Textual TUI that exposes agent activity instead of hiding it
• Tool calling with highlighted diffs before direct file mutations
• Session persistence, resume flow, and context compaction
• Skills, provider adapters, and clean modules for study and modification

Configuration

Create a starter config:

firstcoder config init
firstcoder config path
firstcoder config show

Keep secrets in environment variables:

export FIRSTCODER_API_KEY="your-api-key"

Default config locations:

global:  ~/.config/firstcoder/config.toml
project: ./firstcoder.toml

Provider support is centered on the OpenAI Chat Completions-compatible path and a native Anthropic Messages API adapter. Both paths implement the same internal complete/streaming contracts (text deltas, tool-call accumulation, forced tool_choice, usage, and PROMPT_TOO_LONG-style error classification). The TUI's native multimodal input can stage pasted file paths and clipboard images; images and small text files then travel through the session/context pipeline to providers that support vision. Model and provider vision capability still matters. Anthropic-only extras such as prompt caching remain optional future work. FirstCoder does not use the OpenAI Responses API yet.

Multiple models and request options

You can keep several provider/model profiles in one global or project TOML file. Project values are merged over global values, so a project can override only the fields it needs:

default_model = "yuren/gpt-5.6-terra"
task_boundary_classifier_model = "yuren/gpt-5.6-luna"

[providers.yuren]
type = "openai-compatible"
base_url = "https://yurenapi.cn/v1"
api_key_env = "YURENAPI_API_KEY"

[models."yuren/gpt-5.6-terra"]
label = "Yuren Terra"
context_window = 128000

[models."yuren/gpt-5.6-terra".request]
temperature = 0.2
max_tokens = 8192
reasoning_effort = "high"
extra_body = { reasoning_summary = "auto" }

[models."yuren/gpt-5.6-luna"]
label = "Yuren Luna (task-boundary classifier)"

Use firstcoder --model provider/model to choose the initial profile for a run. In the TUI, /models opens the configured model picker and /model provider/model switches immediately. firstcoder config show prints the configured model references and labels, but never prints API keys, environment-variable values, request bodies, or model-state contents.

temperature, max_tokens, and extra_body are sent with the main model request. reasoning_effort is represented as a request extension and passed through when the selected provider supports it; providers that do not recognize it may reject or ignore it. Internal classifiers and compact summarization keep their own bounded token budgets.

task_boundary_classifier_model is optional. When set, hidden task-boundary requests use that fixed model profile while the main agent and L4 compaction keep using the selected main profile. It may point to another model under the same provider, so it reuses that provider's API-key environment variable and base URL. Its temperature and request extensions are inherited, but its output remains capped at 512 tokens; provider/format failures still fall back to the existing conservative uncertain decision.

A small detail for observant users: some provider/model combinations give the TUI topbar a little more character.

TUI

FirstCoder's TUI is designed to expose the agent loop instead of hiding it. You can see session state, streamed assistant output, tool calls, tool results, and permission prompts in one place.

Before write, edit, apply_patch, or delete changes local files, FirstCoder builds a trusted unified diff with red removals, green additions, per-file statistics, and bounded expansion controls. In standard mode it accompanies the normal permission confirmation; an existing grant or aggressive mode still requires a review-only Apply confirmation. Approve the reviewed operation, deny it, or reply with reject: <feedback> so the model can revise the proposed change. FirstCoder rechecks reviewed file snapshots immediately before dispatch and blocks stale operations, reducing accidental overwrites from concurrent changes; this is a guard, not a filesystem-level atomic transaction. In bypass mode the review is shown as a non-blocking event and the operation proceeds immediately; the Harbor adapter disables that event for its non-interactive task turn. Shell commands follow the permission policy for the active mode because arbitrary command effects cannot be precomputed safely.

Ready state:

Conversation flow:

Documentation

• Technical Docs Index
• Chinese Docs Index
• Architecture
• Codebase Reading Guide
• Multimodal Input Design
• MCP Client Configuration
• Harbor Evaluation

Development

Install dev dependencies:

python -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"

Run all tests:

.venv/bin/python -m pytest

Run a focused test file:

.venv/bin/python -m pytest tests/test_app_tui.py -q

Philosophy

FirstCoder was built to answer a question most coding agents do not address:

What actually happens inside when an agent streams, calls tools, asks for permission, compacts context, and resumes a session?

It is a real runnable agent, but it is also a readable Python project you can learn from one subsystem at a time.