# FirstCoder: A Local Coding Agent Built to Be Read, Not Just Run

> FirstCoder is a small Python coding agent with a TUI, tool calling, and permissions, designed for engineers who want to study agent internals. This review covers its architecture, setup, and where it falls short of production tools.

**KomorGiaoGiao/FirstCoder** — FirstCoder is an open-source local coding agent that’s useful enough to run, small enough to read end to end, and structured enough to learn from. If you’re building your own agent, it’s a practical reference—not a black box.

- Repository: https://github.com/KomorGiaoGiao/FirstCoder
- Website: https://komorgiaogiao.github.io/FirstCoder/
- Stars: 226 · Forks: 27
- Language: Python
- License: MIT
- Published: 2026-08-24 · Updated: 2026-08-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/komorgiaogiao-firstcoder

## What FirstCoder Solves and Who It Is For

FirstCoder addresses a specific gap in the coding-agent ecosystem: most projects show the surface of what an agent does, but hide the machinery. The README states that FirstCoder is built to make agent internals visible, with a focus on the loop, tool calling, permissions, sessions, and context handling. It is for engineers who want to study how a coding agent is assembled, modify or extend a local Python implementation, and understand the architecture well enough to explain it in an interview. The project is not aiming to out-feature larger agents. Instead, it positions itself as a practical reference, not a black box. The intended audience is people who learn by reading code and who want a runnable system, not just a tutorial or a demo.

## The Architecture: Small Codebase, Clear Module Boundaries

The codebase is roughly 25,000 lines of Python under the `firstcoder/` directory, spanning 174 files. That is small enough to read end to end, according to the project's claims. The README emphasizes clear module boundaries, which suggests that subsystems like tool calling, permissions, sessions, and context compaction are separated into distinct modules. The architecture includes a Textual TUI, provider adapters, and a session pipeline that handles images and small text files. The agent loop is the core, and the documentation says detailed subsystem design lives in the docs, not the README. This is a deliberate trade-off: the project drops some platform surface area to stay inspectable. For a reader, this means you can trace how a message flows from the TUI to a provider and back, without wading through hundreds of thousands of lines.

## Getting It Running: Commands and Configuration

Installation is straightforward with `pipx install firstcoder`. After that, you start the TUI with `firstcoder`. For one-off queries, use `firstcoder --message "Summarize this repository in one paragraph"`. There is also a line-oriented interactive mode via `firstcoder --interactive`. Configuration begins with `firstcoder config init`, and you can locate the config file with `firstcoder config path` and view it with `firstcoder config show`. Secrets go into environment variables, such as `export FIRSTCODER_API_KEY="your-api-key"`. Config files live in `~/.config/firstcoder/config.toml` for global settings and `./firstcoder.toml` for project-level overrides. The TOML format supports multiple provider and model profiles. A project can override only the fields it needs, because project values are merged over global values. The README gives an example with a provider named `yuren` and two models, including a `task_boundary_classifier_model` for hidden classification requests.

## How It Works: Provider Adapters and the Agent Loop

FirstCoder centers on two provider paths: the OpenAI Chat Completions-compatible path and a native Anthropic Messages API adapter. Both implement the same internal contracts for text deltas, tool-call accumulation, forced `tool_choice`, usage, and error classification like `PROMPT_TOO_LONG`. This means the core agent loop is provider-agnostic, which is good for study. The TUI supports multimodal input, staging pasted file paths and clipboard images, and those travel through the session and context pipeline to providers that support vision. The README warns that model and provider vision capability matters. Anthropic-only extras, such as prompt caching, are optional future work. The project does not use the OpenAI Responses API yet, so if you rely on that API, this is a limitation. The agent loop is the heart of the system, but the README does not detail the exact loop steps; that is left to the docs.

## Configuration Depth: Models, Request Options, and Safety

The configuration system allows multiple provider and model profiles in one TOML file. You can set `default_model` and `task_boundary_classifier_model` separately. Each model entry can have a `label`, `context_window`, and a `request` block with `temperature`, `max_tokens`, and `extra_body`. The README shows an example with `reasoning_effort = "high"` and `extra_body = { reasoning_summary = "auto" }`. These are passed through to the main model request, but `reasoning_effort` is a request extension, and providers that do not recognize it may reject or ignore it. Internal classifiers and compact summarization keep their own bounded token budgets. A notable safety feature is that `firstcoder config show` prints model references and labels but never prints API keys, environment-variable values, request bodies, or model-state contents. That is a thoughtful touch for a local tool that handles secrets.

## Limitations and Failure Modes

FirstCoder is not a production-grade platform. The README explicitly compares itself to larger projects like OpenCode, which has roughly 575,000 lines of TypeScript and JavaScript, and accepts that FirstCoder drops extra platform surface area. One concrete limitation is the lack of Anthropic-only extras like prompt caching, which are listed as optional future work. Another is that the OpenAI Responses API is not supported, so if you need that, this is the wrong tool. The `reasoning_effort` extension may be rejected by some providers, which could cause request failures. The TUI's multimodal input depends on the provider's vision support, so using a text-only model with images will fail. Also, the README mentions a Harbor evaluation integration and broad pytest coverage, but no release history is available, so the maturity of the test suite is not independently verified.

## Comparison with OpenCode and Learning-Oriented Repos

The README includes a direct comparison with OpenCode, which is a larger, multi-surface coding-agent platform. OpenCode's primary goal is to deliver a broader production-style platform, while FirstCoder focuses on readability and teachability. The engineering trade-off is clear: FirstCoder stays small and inspectable, while OpenCode accepts complexity to support a broader product surface. Compared with many learning-oriented agent repos, FirstCoder claims to have real TUI, tools, permissions, sessions, and provider adapters, not just a single tutorial path. It also claims broad pytest coverage and a Harbor evaluation integration. The practical difference is that FirstCoder is meant to be extended and adapted into a portfolio project, while many learning repos are only for following along. If you want a full-featured agent for daily production use, OpenCode is the alternative, but you will trade away the ability to read the entire codebase easily.

## Maintenance and License Implications

The project is licensed under the MIT license, which is permissive and allows modification and reuse with attribution. The README does not provide details on release cadence or maintenance history, and no recent releases were retrieved. The last push date is unknown, so the project's activity level is unclear. This matters if you plan to depend on it long-term. The codebase is small enough that you could fork it and maintain your own version, which aligns with the project's goal of being a learning resource. The documentation mentions a Harbor evaluation integration, which suggests some testing infrastructure exists, but you should verify the current state of the test suite before relying on it. The license allows commercial use, but you are responsible for compliance with the MIT terms, including preserving copyright notices.

## Conclusion

Adopt FirstCoder if you are a developer or student who wants to understand coding-agent internals by reading and modifying a small, testable Python codebase. Skip it if you need a production-grade agent with broad platform support or advanced Anthropic features. Before adopting, verify that the provider you plan to use is OpenAI-compatible or Anthropic Messages API-compatible, and confirm that your model supports vision if you need image input. Check the current state of the repository's tests and documentation, as the README references a Harbor evaluation integration but no release history is available.

## FAQ

### How do I install FirstCoder and run a single message without the TUI?

Install it with `pipx install firstcoder`, then pass the message as an argument: `firstcoder --message "Summarize this repository in one paragraph"`. Python 3.11 or higher is required. The bare `firstcoder` command opens the Textual TUI and `--interactive` selects the line-oriented mode.

### Where does FirstCoder keep its configuration?

In two TOML files, a global one at ~/.config/firstcoder/config.toml and a project one at ./firstcoder.toml, with project values merged over global ones. `firstcoder config init` creates a starter file, `config path` shows the locations and `config show` prints model references and labels while never printing API keys, environment-variable values, request bodies or model-state contents.

### Which model APIs does FirstCoder support?

An OpenAI Chat Completions-compatible path and a native Anthropic Messages API adapter, both implementing the same internal streaming and tool-call contracts. It does not use the OpenAI Responses API yet, and Anthropic-only extras such as prompt caching remain optional future work.

### What does task_boundary_classifier_model do in FirstCoder?

It is an optional model profile used for the hidden task-boundary requests while the main agent and compaction keep using the selected main profile. It may point at another model under the same provider, reusing that provider's API key environment variable and base URL, and it inherits the temperature and request extensions of whatever it points at.

### Why would someone read FirstCoder instead of a larger coding agent?

The README states the trade directly: roughly 25k lines of Python under `firstcoder/` across 174 files, against roughly 575k lines of TypeScript and JavaScript for larger projects, with extra platform surface deliberately dropped so the system stays inspectable. The stated use cases are studying how a coding agent is assembled, extending a local Python implementation, and understanding the architecture well enough to explain it.

## Sources

- [Official documentation](https://komorgiaogiao.github.io/FirstCoder/)
- [Official README](https://github.com/KomorGiaoGiao/FirstCoder#readme)
- [Project repository](https://github.com/KomorGiaoGiao/FirstCoder)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/komorgiaogiao-firstcoder