teenycode

A tiny code‑editing agent in TypeScript (200 LOC) — a minimal, hackable CLI that talks to OpenAI and can read, list, and edit files in your working directory.

This repository is for educational purposes, to demonstrate the core elements of a minimal CLI coding agent, adapted from How to Build an Agent by Amp.

Features

• Chat-based CLI that calls OpenAI and uses tool calls
• File tools: read_file, list_files, edit_file (single, unique replacement or create new file)
• Prefers reading files over guessing; makes the smallest edit that satisfies a request
• Minimal dependencies and simple code you can tweak

Note

No bash tool is included because it can be risky and this repo is intended for educational use. You can add it yourself if needed.

Requirements

• Node.js 22+
• npm / Vite Plus
• An OpenAI API key

Quickstart

Try it immediately, without cloning the repo (you will need your own OpenAI API key):

export OPENAI_API_KEY=sk-...
npx teenycode

Or put OPENAI_API_KEY=sk-... in a .env file in the directory where you run npx teenycode.

If you prefer a one-liner:

OPENAI_API_KEY=sk-... npx teenycode

Alternatively, run it from source by cloning the repo:

npm install
cp .env.example .env # Then edit .env and set OPENAI_API_KEY
npm start

You'll see a prompt like Chat with <model>. Type your requests. Quit with exit, quit, :q, or Ctrl‑C.

If OPENAI_API_KEY is missing, the CLI prints setup instructions and exits.

How it works

• src/index.ts: Entry point; checks OPENAI_API_KEY, starts the agent
• src/agent.ts: Chat loop, tool routing, and message state
• src/tools.ts: Three built-in tools implemented with Node fs APIs

The agent uses OpenAI Chat Completions with function/tool calling. Tool inputs are validated with Zod, and schemas are exported to JSON Schema for the model.

Example

➜  teenycode git:(main) ✗ OPENAI_API_KEY=sk-... npx teenycode

Chat with gpt-5 (type 'exit' or 'quit' or use Ctrl-C to quit)

You: What is this repo about?

Tool: list_files({"path": ""})
Tool: read_file({"path":"README.md"})
Tool: read_file({"path":"package.json"})
Tool: read_file({"path":"src/index.ts"})
Tool: read_file({"path":"src/agent.ts"})
Tool: read_file({"path":"src/tools.ts"})

Agent: TeenyCode is a tiny, hackable CLI coding agent written in TypeScript (~200 LOC) for educational purposes. It chats with OpenAI and can operate on your local files via three tools:
- read_file: read a file’s contents
- list_files: list files/dirs at a path
- edit_file: make a single, unique text replacement or create a new file

Tools

The agent exposes three file tools:

• read_file (path: string): Reads and returns the text contents of a file at a relative path.
• list_files (path: string): Lists files and directories at the given path (use "." for the current dir).
• edit_file (path: string, old_str: string, new_str: string): Replaces exactly one occurrence of old_str with new_str in the given file.

Conventions:

• All paths are relative to your current working directory.
• The agent prefers reading over guessing and aims to make the smallest possible change.

Notes

• Edits are surgical by design. Keep your work in git and commit often.
• The agent operates relative to your current working directory.

Local development

vp install
cp .env.example .env
# edit .env and set your API key
vp run start

Quality checks

vp check
vp lint --fix
vp fmt
vp test
vp build

Acknowledgements

Adapted from How to Build an Agent by Amp.