FirstCoder

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

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.

FirstCoder planning, requesting permission, and completing a local task

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.

Dimension	FirstCoder	Larger projects like OpenCode
Primary goal	Make agent internals readable and teachable	Deliver a broader production-style coding-agent platform
Codebase shape	Roughly 17k lines of Python runtime code in this repo	Roughly 575k lines of TS/JS across a much larger multi-surface codebase
Engineering tradeoff	Drops some extra platform surface area to stay inspectable	Accepts more complexity to support a broader product surface
Best fit	Learning, modification, interview prep, portfolio projects, and local experimentation	Users who want a larger, more full-surface coding-agent environment

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.

Dimension	FirstCoder	Many learning-oriented agent repos
Learning value	Readable subsystem boundaries and explicit docs	Often optimized for a single tutorial path or demo flow
Practical surface	Real TUI, tools, permissions, sessions, provider adapters	Often focused on a narrower loop or a simpler proof of concept
Verification	80+ test files and multiple benchmark entry points	Often lighter on testing and benchmark integration
Extension path	Easier to adapt into a portfolio or resume project	Often better for following along than for long-term extension

In this repo, the learning goal is important, but it is paired with enough runtime structure, tests, and benchmark hooks 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 permission checks before risky actions
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. The OpenAI-compatible 流式 adapter is the mainline streaming implementation and normalizes provider errors such as PROMPT_TOO_LONG. The Anthropic provider is still 实验性 and does not yet expose Anthropic 原生 thinking/cache/streaming. FirstCoder does not use the OpenAI Responses API yet, so native reasoning and 多模态 support are future provider work rather than current runtime behavior.

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.

Ready state:

FirstCoder ready state

Conversation flow:

FirstCoder conversation flow

Documentation

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.