MasterCode is a coding agent for the terminal, built from scratch in TypeScript to understand how agents like Claude Code, Codex and Gemini CLI work under the hood. You start it in a project folder and ask in plain words; it reads files, edits them and runs commands, and asks your permission before it acts. It draws its screen with mastertui, a terminal UI library built alongside it to replace Ink and React.
Main Features
Chat
Ask in plain words from the folder you want it to work on; the reply streams in word by word
Stop a reply with esc or ctrl+c; the conversation stays
Paste code: every line survives, and you can add lines and move around in it
Tools
Reads files, edits them and runs shell commands
Asks before it runs anything; you answer y or n
Stays inside the project folder; paths outside it are refused
Your project's rules
Follows the project's AGENTS.md, including the ones in folders it opens
Uses Agent Skills (SKILL.md) when a task matches one
Models
Any model through OpenRouter, or OpenAI directly
/model picks one from OpenRouter's live catalogue, with a filter
While you are away
The tab title says when it is working, when it needs you, and when it is done
A notification when it needs your answer or has finished, only if you are in another window
Cmd-click a link or a file path in a reply to open it
mastertui, the terminal library under it
Streams without flicker: only the characters that changed are redrawn
Finished messages are printed once and never redrawn, so a conversation can run forever
Exactly one thing receives each key, so an approval question never steals your typing
Structures
4 Repositories
cli (the agent)
tui (mastertui)
mastertui-docs (the library's documentation site)
playground (a small test project for trying the agent)
Tech Stack & Libraries
The stack
Layer
Built with
Agent
TypeScript 7 · Node.js · pnpm workspace
Models
OpenAI SDK: OpenAI's Responses API, and any model through OpenRouter
mastertui: no React, no layout engine, no native code
Replies
marked, drawn as terminal text by its own renderer
Docs site
Astro + Starlight
Tests
Vitest · xterm headless (checks what the screen really shows)
Engineering highlights
No agent framework: the agent is a loop, events and a switch on what the model answered: text, or a tool to call.
Model-agnostic: everything that talks to a model goes through one interface, so changing provider doesn't touch the loop.
Safe by default: every tool asks before it runs unless it is marked safe, and file paths can't leave the project.
Its own terminal library: Ink and React were replaced by mastertui, built for what an agent needs (streaming, long conversations, approvals while typing).
Written down as it was built: a 10-chapter guide, "Building a Coding Agent From Scratch", and a documentation site for the library.
Tested: 297 tests in the agent and 487 in the library.
Architecture
The parts
Repo
What it does
cli
The agent: chat screen, the loop, model providers, tools
tui
mastertui: drawing, keys, input, scrollback
mastertui-docs
The library's documentation website
playground
A small project to try the agent on
How one request travels
You type "list the files in src/tools" and press Enter.
The runtime adds it to the conversation and hands it to the agent.
The agent sends the conversation and the list of tools to the model.
The model asks to run ls src/tools. The agent checks the request and asks you: y or n.
You press y; the command runs, and its output goes back to the model.
The model answers in text, which streams onto the screen, and the turn ends.
Why it is built this way
One layer, one job: the screen never talks to the tools, and the runtime doesn't know what a tool is, so each part can be tested and replaced alone.
Approval is something the whole turn waits on: the agent pauses until you answer, and stopping the reply also cancels the question.
Some rules need code, not words: prompting the model only changes the odds, so the important safety rules are checked in code.