agent-from-scratch

A minimalistic AI agent harness, built from scratch - to learn how they actually work.

No frameworks. No magic. Just an agent loop, a tool interface, and the wires you need to see them work.

Features

• No framework - pure TypeScript, easy to read and understand end-to-end
• Streaming agent loop with tool calling, written as an async generator
• Built-in shell tool with per-call user confirmation (y/n)
• Interruptible - pause and approve every tool invocation
• Pluggable architecture for tools and LLM providers

Quick Start

export OPENAI_API_KEY=...
npm install
npm run dev

Extending the Agent

• Add a tool - drop it in src/tools/ and bind it in src/index.ts
• Customize prompt - edit PROMPT.md
• Add a provider - implement one in src/llm-providers/ alongside openai.ts
• Tweak behavior - edit the system prompt in src/agent.ts

Project Layout

.
├── PROMPT.md
├── README.md
├── package-lock.json
├── package.json
├── src
│   ├── agent.ts
│   ├── index.ts
│   ├── interrupt.ts
│   ├── llm-providers
│   │   └── openai.ts
│   ├── messages.ts
│   ├── tool.ts
│   └── tools
│       ├── applyDiffs.ts
│       ├── deletePath.ts
│       ├── grep.ts
│       ├── mkdir.ts
│       ├── readFile.ts
│       ├── shell.ts
│       └── writeFile.ts
├── tsconfig.json
└── tweets.md

License

MIT © Miguel Garcia