FirstCoder

What FirstCoder is for

FirstCoder is a real, runnable local coding agent with a Textual text interface, tool calling, permissions, sessions, and context compaction. The README says it is designed to be useful in daily work and easy to study in code, and it keeps the moving parts visible instead of hiding them behind a black box. The stated audience is people who want to understand how coding agents actually work: the agent loop, tool calling, permissions, sessions, and context handling. The project is built to be small enough to read end to end while still being real enough to use, and the README compares it with larger projects such as OpenCode, noting FirstCoder is intentionally smaller in scope with roughly 25,000 lines of Python across 174 files under the firstcoder directory, against the roughly 575,000 lines of TypeScript and JavaScript in a much larger multi-surface codebase. The engineering tradeoff is that FirstCoder drops some extra platform surface area to stay inspectable. The README also contrasts it with tutorial-first learning repos by pointing to broad pytest coverage and one Harbor evaluation integration, arguing that the project stays close to a small but testable engineering system rather than a single demo flow. The goal is not to out-feature a bigger agent but to keep each subsystem understandable.

What you get and how to run it

The README lists what a user gets: a local Python coding agent, a Textual interface that exposes agent activity instead of hiding it, tool calling with marked diffs before direct file mutations, session persistence with a resume flow and context compaction, and skills, provider adapters, and clean modules for study and modification. Installation is through pipx with the command pipx install firstcoder, after which firstcoder starts the text interface and firstcoder with a message flag runs one message without opening the interface. A line-oriented interactive mode is available with the interactive flag. Configuration uses a starter config built by config init, with global and project locations at dot config and the project directory, and secrets are kept in environment variables, including the project's dedicated API credential variable. Provider support centers on the OpenAI Chat Completions-compatible path and a native Anthropic Messages API adapter, both implementing the same internal contracts for text deltas, tool-call accumulation, forced tool choice, usage, and prompt-too-long error classification. The text interface can stage pasted file paths and clipboard images for multimodal input, and the README notes that model and provider vision capability still matters and that Anthropic-only extras such as prompt caching remain optional future work. FirstCoder does not use the OpenAI Responses API yet.

How the interface handles file changes

A detailed section explains how FirstCoder treats file mutations as a reviewable event rather than a silent action. 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 this diff accompanies the normal permission confirmation; an existing grant or aggressive mode still requires a review-only apply confirmation. The user can approve the reviewed operation, deny it, or reply with a reject and feedback so the model can revise the proposal. FirstCoder rechecks reviewed file snapshots immediately before dispatch and blocks stale operations, reducing accidental overwrites from concurrent changes, and the README is careful to call this a guard rather than a filesystem-level atomic transaction. In bypass mode the review is shown as a non-blocking event and the operation proceeds immediately, while 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. The documentation section points to an architecture file, a codebase reading guide, a multimodal input design note, an MCP client configuration, and a Harbor evaluation readme, so a reader who wants to go deeper has a clear path beyond the introduction.

Editorial conclusion

FirstCoder is released under the MIT license, is written in Python, and was last updated on GitHub on 2026-08-24 with 175 stars recorded at the time of the snapshot.