ERKU

A from-scratch terminal AI coding agent — small, transparent, built to learn from.

What is erku?

erku is a small but real AI agent that lives in your terminal. You talk to it, and it reads and edits your code, runs commands, and builds web pages — like Claude Code, just small and transparent: every part is simple and commented so you can see how it works.

It streams its replies live (token by token), keeps a per-project memory, and confines itself to the folder you launch it in.

⚡ Install

npm install -g @erekleeanizhashvili/erku

You'll need an OpenRouter API key (get one at https://openrouter.ai/keys). Put it in a .env file in the folder you run erku from:

# .env
OPENROUTER_API_KEY=sk-or-v1-...

…or export it in your shell:

export OPENROUTER_API_KEY=sk-or-v1-...

🚀 Usage

Go to the folder you want to work in and run:

erku

Then just talk to it — "add a dark mode toggle to index.html" or "find the bug in login.ts and fix it" — and it gets to work. Reply in any language; it answers in the language you write in.

Run without asking (it acts on its own, but still refuses catastrophic commands):

erku --dangerously-skip-permissions

🎛️ Commands

Type / and a live menu appears (navigate with arrows / Tab):

| Command | What it does | |---|---| | /help | list the commands | | /permission | switch mode: ask / auto / read-only (or press Shift+Tab to rotate) | | /model | switch model — /model gemini searches OpenRouter's full catalog with prices | | /context | show how many tokens are used vs the limit | | /clear | clear the conversation (fresh start, no restart) | | /resume | reload a previous session | | exit | quit |

Permission modes: ask confirms every change · auto does everything itself · read-only lets the agent only read/search/browse — it can't change files or run commands.

🧠 Project memory

Drop an erku.md file in your project and erku reads it on every run — put your project's rules and facts there so you don't have to repeat them:

# Project memory
- This site uses a blue theme.
- Prices are always in GEL.
- Text in Georgian.

The agent can also save durable facts itself with the remember tool (stored in .erku/memory.md), so it recalls them in later sessions.

🛠️ Your own commands (skills)

Create a markdown file at .erku/skills/<name>.md and it becomes the /<name> command — the file's text is run as an instruction. Use $ARGUMENTS to pass along whatever you type after it. No code changes needed.

✨ What it can do

• Files — create / read / edit (atomic writes so a crash can't corrupt a file)
• Explore — search, list_dir, ranged reads (offset/limit) that stream huge files
• show — display a file to you without spending the model's context on it
• Run commands — bash (a timeout kills the whole process group, so no orphan dev-servers)
• Web — web_search + web_fetch (SSRF- and DNS-rebinding-safe)
• Local preview server for the pages it builds
• Streaming — replies appear live, token by token
• update_todos — a live checkbox plan for multi-step work
• Sessions — saved automatically, reload with /resume
• Auto-compaction of long conversations, and a loop-detector so it doesn't get stuck
• Multimodal — paste an image with Ctrl+V (auto-switches to a vision model)

🔒 Safety

• ask mode (default) confirms before every change.
• auto acts on its own but still blocks catastrophic commands (rm -rf /, curl | sh, …).
• read-only mode blocks all changes entirely.
• Root confinement — it works only inside the folder you launched it in.
• Secret files (.env, *.pem, id_rsa, …) aren't read without your OK, and search skips them.
• Your API key stays on your machine (.env) — it's never committed or published.

🎓 About

erku was built step by step, to learn from — to understand how an AI agent works from the inside: model + memory + tools + the agent loop + safety nets. The code is deliberately small and commented. Contributions and forks welcome.