Simple Coder is a terminal-based coding assistant. It is intentionally minimal and unoptimized as its purpose is to serve as a learning resource demonstrating how equipping a model that is good at tool use with a decent-ish prompt & a set of tools can enable "agentic" behavior. As such, it is not published anywhere nor is it recommended for production use.

• Chat in your terminal; the assistant can inspect and change files in the current project.
• Uses the AI SDK (ai) with OpenAI (@ai-sdk/openai) and a simple system prompt.
• Streams tokens smoothly and prints structured tool-call/results to the console.

• editFile: Applies line-based edits and returns a unified diff, lines changed, and totals.
• executeCommand: Executes a command in the terminal.
• listFiles: Lists files/folders in a directory with basic metadata. Ideal for discovery.
• readFile: Reads a file as lines (with optional line range), preserving EOL info.

All tools resolve paths relative to process.cwd() — i.e., whatever directory you run the CLI from.

# Using pnpm (recommended)
pnpm install

Set your OpenAI API key using either method:

Option A: Environment variable (recommended for CLI usage)

export OPENAI_API_KEY=sk-...

Option B: .env file (convenient for development)

echo "OPENAI_API_KEY=sk-..." > .env

By default the app uses OpenAI's gpt-5 model via the AI SDK. See the ai-sdk documentation on providers if you would like to use a different provider and/or model.

This package is NOT published and will never be. The only way to use it within a codebase other than this one directly is to follow either of the following methods (geared towards pnpm), which will allow you to use the scoder CLI from any directory.

1. Global link (best for development)

# In this repo
pnpm build
pnpm link -g

# Now, from any other project directory
cd /path/to/another/project
OPENAI_API_KEY=sk-... scoder
# Or export it for the session:
# export OPENAI_API_KEY=sk-...
# scoder

2. Global install from a local tarball

# In this repo
pnpm build
pnpm pack   # creates something like bim-bimfyi-simple-coder-1.0.0.tgz
pnpm add -g ./bim-bimfyi-simple-coder-*.tgz

# Use it anywhere
cd /path/to/another/project
OPENAI_API_KEY=sk-... scoder
# Or export it for the session:
# export OPENAI_API_KEY=sk-...
# scoder

• Ensure your global pnpm bin is on PATH: echo $(pnpm bin -g).
• The assistant edits files relative to the directory you run it from.
• For quick personal use, you can also alias the built script: alias scoder='node /absolute/path/to/simple-coder/dist/index.js' (after pnpm build).

pnpm dev      # run with tsx watch
pnpm build    # type-check and emit to dist/
pnpm start    # run built app from dist/

pnpm test         # run tests with Vitest
pnpm test:ui      # run tests with UI
pnpm test:coverage # run tests with coverage report

• pnpm lint: Lint and auto-fix code issues
• pnpm format: Format code with Biome
• pnpm check: Run all checks without auto-fixing
• pnpm typecheck: Run TypeScript type checking

MIT — see LICENSE.