Skillget

FirstCoder

agent
Security Audit
Fail
Health Pass
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Community trust — 54 GitHub stars
Code Fail
  • rm -rf — Recursive force deletion command in benchmark/chainswe/docker_runner.py
  • rm -rf — Recursive force deletion command in benchmark/harbor/firstcoder_agent.py
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

FirstCoder——你见过的最好的可读可用可学的agent项目，将它加入你的作品集和简历项目当中吧

README.md

FirstCoder logo

FirstCoder

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

Python Textual TUI OpenAI Compatible pytest Ask DeepWiki

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.

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.

Reviews (0)

No results found