MasterCode

Overview

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

LayerBuilt with
AgentTypeScript 7 · Node.js · pnpm workspace
ModelsOpenAI SDK: OpenAI's Responses API, and any model through OpenRouter
Toolsexeca (shell commands) · diff (edits) · Zod 4 (checks every tool's input)
Terminal UImastertui: no React, no layout engine, no native code
Repliesmarked, drawn as terminal text by its own renderer
Docs siteAstro + Starlight
TestsVitest · 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

RepoWhat it does
cliThe agent: chat screen, the loop, model providers, tools
tuimastertui: drawing, keys, input, scrollback
mastertui-docsThe library's documentation website
playgroundA small project to try the agent on

How one request travels

  1. You type "list the files in src/tools" and press Enter.
  2. The runtime adds it to the conversation and hands it to the agent.
  3. The agent sends the conversation and the list of tools to the model.
  4. The model asks to run ls src/tools. The agent checks the request and asks you: y or n.
  5. You press y; the command runs, and its output goes back to the model.
  6. 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.

UI Interfaces