Agent Boilerplate

Small console agent boilerplate with a REPL loop. It loads a base prompt, sends messages to OpenRouter, and exposes a limited set of safe tools (file reading, patching, searching, command execution with confirmation, and website visits).

This is an educational project and a free-to-use boilerplate to build console agents.

IMPORTANT NOTICE

WARNING: The agent can access the system through tools, so be very careful with the requests you make. Avoid asking for sensitive or destructive actions without reviewing them first.

Consider using COMMAND_MODE, which is not automatic and is configured in .env:

• COMMAND_MODE=confirm (default) asks for confirmation before each command.
• COMMAND_MODE=auto runs allowed commands without per-command confirmation.

This mode only changes the confirmation step; it does not remove the restrictions enforced by .paths and .whitelist.

What it includes

• TypeScript CLI with an interactive REPL.
• Loads prompt.txt on startup.
• Configuration via .env.
• Allowlist-based file and command access.
• Console output with readable formatting.

Requirements

• Node.js 18+
• npm

Installation

npm install

Playwright dependencies

npx playwright install

Configuration

1. Copy .env.example to .env.
2. Fill in:

• OPENROUTER_API_KEY
• OPENROUTER_BASE_URL
• OPENROUTER_MODEL

Usage

npm run agent

Structure

• src/cli.ts starts the REPL.
• src/agent/agent.ts runs the core loop and tool execution.
• src/tools/ contains the tools exposed to the model.
• prompt.txt is the base prompt.
• .paths defines allowed file access.
• .whitelist defines allowed command prefixes.
• .memory is an optional notes file (not versioned).

Security notes

exec_command only allows prefixes listed in .whitelist and either asks for confirmation (confirm) or runs automatically (auto). File access follows .paths.

.paths

.paths defines which paths are allowed or denied for read/write access. By default, sensitive system folders are blocked, and only paths permitted by these rules are accessible.

.whitelist

.whitelist defines the command prefixes that exec_command is allowed to run. If a command does not match an allowed prefix, it is rejected even if the user requests it.

How an AI agent with tools works

Think of the agent as a loop that alternates between "thinking" and "doing". The model does not directly access your files or run commands. It asks for tools, and your agent executes them safely.

┌──────────────┐
│ User message │
└──────┬───────┘
       │
       v
┌───────────────────────────┐
│ System prompt + tool list │
└──────────┬────────────────┘
           │
           v
┌───────────────────────────┐
│ LLM: answer or tool call? │
└───────┬───────────┬───────┘
        │           │
        │ answer    │ tool call
        v           v
   ┌─────────┐  ┌─────────────────┐
   │ Reply   │  │ Run tool safely │
   └────┬────┘  └────────┬────────┘
        │               │
        │               v
        │      ┌──────────────────┐
        └----> │ Tool result to LLM│
               └─────────┬────────┘
                         v
                  ┌─────────┐
                  │ Reply   │
                  └─────────┘

Tool calling, step by step

1. The user types a message in the REPL.
2. The agent sends: system prompt + conversation + tool schema.
3. The model can respond with a tool call (name + JSON args).
4. The agent validates the request, enforces allowlists, and runs the tool.
5. The tool output is appended to the conversation.
6. The model uses that output to answer or request another tool.

Why this is safe

• Tools are explicit and limited in scope.
• File access is restricted by .paths.
• Command execution is restricted by .whitelist and always asks for confirmation.

In this repo

[User] -> [REPL] -> [OpenRouter]
                -> tool call? ----- yes ---> [Run tool] -> [Result] -> [Answer]
                               \--- no ----> [Answer]