Agent Builder

Agent Builder

A local-first agent harness. Zero dependencies, one file, real work.

Chat. Build. Run.

What is this?

An agent harness (agent.stub) — a complete runtime that AI coding assistants transform into working agents. It handles the execution loop: tool dispatch, turn management, context compression, subagent spawning, and safety gates. You describe what you want, AI fills in the persona and tools, and the harness runs it.

You describe what you want → AI customizes the harness → Working agent in seconds

The harness creates:

• Tool-using agents — files, web, APIs, anything
• Reasoning agents — step-by-step problem solving with subagent decomposition
• Self-extending agents — create new tools on-the-fly at runtime
• Knowledge agents — build a compounding wiki from raw sources that grows richer over time
• Skill-driven agents — drop SKILL.md bundles into ./skills/ and the agent opens them on demand
• MCP-connected agents — point a mcp.json at any MCP server (filesystem, GitHub, Postgres, Slack, …) and its tools appear to the agent automatically
• Sandboxed agents — run untrusted scripts inside OCI containers via Apple's native container CLI or Docker

No frameworks. No npm dependencies. Just Node.js and AI.

Choose Your AI Assistant

Various AI coding assistants can transform the agent harness into working agents. These tools understand natural language and can build your agent — pick any one that works for you!

Getting Started

What You Need

• A computer with internet
• Node.js (Download here — installs like any app)
• Git (Windows: Download here; Mac/Linux: usually pre-installed)
• 5 minutes to set up

Opening Terminal

Terminal is an app that lets you type commands.

On Mac:

1. Press Command + Space
2. Type Terminal
3. Press Enter

On Windows:

1. Install Git for Windows from git-scm.com if you haven't already
2. Right-click on your desktop or in a folder
3. Select "Git Bash Here"

On Linux:

1. Press Ctrl + Alt + T

Or search for "Terminal" in your applications

You'll see a window with text and a blinking cursor — this is where you'll type commands!

Three Simple Steps

1. Get the Agent Builder

Run these commands one at a time in Terminal:

First — Copy the agent builder to your computer:

git clone https://github.com/builtbyV/agent-builder.git

Press Enter and wait until the download finishes.

Then — Go into your project folder:

cd agent-builder

Troubleshooting:

• If you see 'No such file or directory', the download probably isn't complete yet. Wait and try again.
• You should see agent-builder in your Terminal prompt after this command

2. Run Setup

In your Terminal window (make sure you're inside the agent-builder folder):

bash setup.sh

Don't worry if you see lots of text scrolling by — this is normal! Just wait until it stops and you see your Terminal prompt again.

This command automatically does everything for you:

• Check your computer is ready
• Install and configure Ollama (local AI)
• Set everything up for you

3. Start Building!

Start your preferred AI coding assistant:

# Examples of starting different AI assistants:
npx claude    # or
npx codex     # or
npx gemini    # or your preferred tool

What this does: Starts an AI assistant so you can chat directly in the Terminal.

That's it! Now just tell your AI assistant what you want:

• "I need an agent that researches tech news"
• "Create an agent that can analyze code for security issues"
• "Build an agent that processes CSV files and creates reports"
• "Make a knowledge agent that compiles articles into a wiki"

If you make a mistake, just tell your AI assistant to fix it — nothing will break!

Helpful Terminal Commands

Just a few commands you might need:

• cd folder-name — Go into a folder
• cd .. — Go back up one folder
• ls — See what's in current folder (works in Git Bash on Windows too)
• pwd — See where you are

Examples:

cd agent-builder   # Enter your project folder
cd ..              # Go back to the previous folder
ls                 # See what files are in current folder
pwd                # Check which folder you're in

Stopping Running Processes:

• Windows/Linux: Press Ctrl + C to stop any running command
• Mac: Press Command + C to stop any running command
• This is useful when you need to stop running agents or Ollama

Features

The harness handles:

• Turn management — turn-aware prompting, context compression, automatic message summarization
• Subagent spawning — decompose big tasks into focused subtasks with fresh contexts via spawn_agent
• Parallel tool execution — independent tool calls run concurrently
• Error recovery — actionable hints on failures (not raw stack traces)
• Safe by default — preview tool calls before execution (--yolo to auto-run); network allowlist on HTTP tools; sandboxed shell via run_in_container

What you get:

• Zero npm dependencies — Just Node.js and Ollama
• Single file — The entire agent in one .js file
• 25 built-in tools — Files, web, search, knowledge base, orchestration, skills, MCP, sandbox
• Dynamic tools — Agent creates tools at runtime as needed
• Knowledge system — Ingest sources, compile a wiki, search with rg/grep, learnings that compound
• Skills (progressive disclosure) — drop SKILL.md bundles into ./skills/ and the harness auto-lists them in the system prompt; bodies load on demand via load_skill. Compatible with npx skills add and the Anthropic/Vercel skill ecosystem
• MCP client (stdio) — point ./mcp.json at any Model Context Protocol server and its tools appear as _ in the agent's registry. No new dependencies
• Container sandbox — run_in_container wraps Apple's native container CLI (macOS Apple Silicon) or Docker, with deny-first networking and safePath-confined mounts
• Network allowlist — HTTP tools gated to a configurable host list; defaults to DuckDuckGo only, extend with --allow-host or AGENT_BUILDER_ALLOW_HOSTS
• Multiple providers — Ollama (local, free), OpenAI, Anthropic, Google

Example Agents

Tell your AI assistant what kind of agent you need:

"Create a research agent that searches the web, cross-references sources,
and compiles findings into structured reports"

"Build a code review agent that analyzes code for security vulnerabilities,
performance issues, and suggests improvements"

"Make a knowledge agent that ingests articles and papers, compiles them
into a wiki of concept articles, and answers questions from the wiki"

"Create a data analyst agent that processes CSV files, identifies patterns,
and generates statistics"

"Build an agent that uses the `filesystem` and `github` MCP servers to keep a
README changelog in sync with recent commits"

"Make an agent that runs Python scripts from ./skills/ inside a container so
nothing escapes the working directory"

Safety First

By default, the agent shows you what it plans to do:

$ node agent.js "Delete old logs"

=== Tool Calls Detected ===
- list_files: {"path": "logs", "pattern": "*.old"}
- delete_file: {"path": "logs/2023-01.old"}
- delete_file: {"path": "logs/2023-02.old"}

Run with --yolo to execute automatically

Review first, then run with --yolo if you approve.

Extend with Skills

Skills are SKILL.md bundles — prose instructions plus optional scripts — that teach an agent a methodology for a domain. The harness auto-lists skills in the system prompt at turn 1 (just name + description, ~100 tokens each) and the agent opens them on demand.

# Drop any SKILL.md bundle into ./skills/
skills/
└── my-skill/
    └── SKILL.md

# Or install from the ecosystem
npx skills add vercel-labs/agent-skills --skill frontend-design -a universal
bash add-skill.sh anthropics/skills/skills/docx   # helper in /Users/vps/desktop/dev/skills/

Agents can also author skills — after finishing a repeatable task, they can call extract_skill to write a draft SKILL.md under ./skills/drafts//. Review and promote:

cat skills/drafts/my-skill/SKILL.md   # review
mv skills/drafts/my-skill skills/my-skill   # promote

See the Skills section in AGENTS.md for the full contract.

Run on a Schedule or Trigger

Agents are just CLI programs, so anything that can run a shell command can trigger an agent. The automation/ folder ships the macOS-native glue (launchd templates, a universal invoke-agent.sh entrypoint with lock files + log rotation, and an inbox/outbox pattern) so you don't have to figure it out:

# Fire every 5 minutes (or daily, or on folder change — pick a template)
cp automation/launchd/timer.plist.template ~/Library/LaunchAgents/ee.agent-builder.MY-AGENT.plist
# Edit: paths, agent file, task, interval
launchctl load ~/Library/LaunchAgents/ee.agent-builder.MY-AGENT.plist

Talk to your agent via Siri, iMessage, or the share sheet — build a Shortcut that writes to automation/inbox/, and launchd wakes the agent on file change. Works with NFC tags, Focus mode, specific-contact messages, or "Hey Siri, ask agent". See [automation/README.md](automation/README.md) for the Shortcuts recipe and six other recipes (schedules, webhooks, Slack/Discord via MCP).

Connect MCP Servers

Agents can talk to any Model Context Protocol server over stdio — filesystem, GitHub, Postgres, Slack, puppeteer, and dozens more. Drop a mcp.json in your working directory:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_…" }
    }
  }
}

On startup the harness spawns each server, pulls its tools, and exposes them as _ (e.g. filesystem_read_text_file, github_create_issue). Full JSONSchema is available on demand via describe_mcp_tool. See the MCP section in AGENTS.md for the full contract.

Built-in Tools

Every agent created from the stub includes:

File Tools         Knowledge Tools         Web Tools
─────────────      ──────────────────      ─────────────
list_files         ingest_source           fetch_url
read_file          read_manifest           search_web
write_file         mark_compiled           scrape_page
delete_file        search_context          download_file
read_section       save_learning

Skills             MCP                     Sandbox
──────────────     ──────────────────      ─────────────
list_skills        describe_mcp_tool       run_in_container
load_skill
discover_skills
extract_skill

Orchestration      Meta Tools
──────────────     ──────────
spawn_agent        define_tool
finish_task        help

The knowledge tools enable a compounding wiki pattern: ingest raw sources → compile into structured articles → maintain an index → every interaction enriches the knowledge base. See AGENTS.md for the full Knowledge Agent Pattern.

The skill tools let an agent explore (list_skills), open (load_skill), discover remote bundles (discover_skills), and capture successful methodologies as drafts (extract_skill) — a full author-consume loop compatible with the Anthropic / Vercel skill ecosystem.

The MCP tool (describe_mcp_tool) surfaces full JSONSchema for any tool from a connected MCP server. Remote tools themselves register as _ — auto-discovered from ./mcp.json.

The sandbox tool (run_in_container) runs shell commands inside an OCI container — prefers Apple's native container CLI, falls back to Docker. Default --network none, safePath-confined mounts.

Claude Code with Ollama (Fully Offline)

You can run Claude Code — the AI assistant that builds your agents — entirely offline using Ollama's Anthropic-compatible API. This means both the agent builder (Claude Code) and the agents it creates run locally.

# Quick setup — launches Claude Code with a local model
ollama launch claude

# Or with a specific model
ollama launch claude --model qwen3.5

Manual setup

# Set environment variables
export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434

# Run Claude Code with an Ollama model
claude --model qwen3.5

Recommended models for Claude Code + Ollama:

| System RAM | Models | |---|---| | 16GB | qwen3.5, glm-4.7-flash | | 32GB | qwen3.5:cloud, glm-5:cloud, kimi-k2.5:cloud | | 64GB+ | minimax-m2.7, qwen3-coder-next, gemma4 |

Cloud models are also available at ollama.com/search?c=cloud. See the Ollama docs for the full documentation index.

> Note: Claude Code requires a large context window. We recommend at least 64k tokens. See the context length documentation for how to adjust context length in Ollama.

Advanced Usage

Command-Line Options

# Basic usage
node my-agent.js "Your task"                                # Preview tool calls
node my-agent.js "Your task" --yolo                         # Auto-execute tools
node my-agent.js --yolo                                     # Run default task

# Working directory and turns
node my-agent.js "Your task" --cwd ./workspace              # Confine file ops
node my-agent.js "Your task" --max-turns 10                 # Override 5-turn default

# Ollama models (local, free)
node my-agent.js "Your task" --model mistral-small          # Default
node my-agent.js "Your task" --model qwen3-coder-next       # Code-focused
node my-agent.js "Your task" --model deepseek-r1            # Reasoning
node my-agent.js "Your task" --model gemma4                 # General + vision

# Cloud providers (require API keys)
node my-agent.js "Your task" --model gpt-5-mini             # OpenAI
node my-agent.js "Your task" --model claude-sonnet-4-5      # Anthropic
node my-agent.js "Your task" --model gemini-2.5-flash       # Google

# Provider prefix format
node my-agent.js "Your task" --model openai:gpt-5
node my-agent.js "Your task" --model anthropic:claude-opus-4-1
node my-agent.js "Your task" --model ollama:mistral-small

# API keys
node my-agent.js "Your task" --openai-key sk-...
node my-agent.js "Your task" --anthropic-key sk-ant-...
node my-agent.js "Your task" --gemini-key AIza...
node my-agent.js "Your task" --save-keys                    # Persist to .env

# Network allowlist (HTTP tools)
node my-agent.js "Your task" --allow-host api.github.com --yolo
node my-agent.js "Your task" --allow-host "*.wikipedia.org" --yolo   # wildcard subdomains
AGENT_BUILDER_ALLOW_HOSTS=api.github.com,raw.githubusercontent.com node my-agent.js "..." --yolo

Dynamic Tool Creation

Agents can create new tools on-the-fly:

>

// Dynamic tools have access to a workspace-confined file helper:
>

Dynamic tools run in a sandbox with access to: fetch, file.read/write/list, args, AppError, assertString, truncate.

Environment Variables

OLLAMA_HOST=http://localhost:11434         # Ollama server (default)
OPENAI_API_KEY=sk-...                      # OpenAI
ANTHROPIC_API_KEY=sk-ant-...               # Anthropic
GEMINI_API_KEY=AIza...                     # Google
OPENAI_BASE_URL=https://...                # Custom API endpoints
ANTHROPIC_BASE_URL=https://...
AGENT_BUILDER_ALLOW_HOSTS=a.com,b.com      # Extend the network allowlist
LOG_LEVEL=debug                            # debug, info, warn, error

Safety Features

Path Protection       Files confined to working direc

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [builtbyV](https://github.com/builtbyV)
- **Source:** [builtbyV/agent-builder](https://github.com/builtbyV/agent-builder)
- **License:** MIT
- **Homepage:** https://oss.v.ee/agent-builder/

Install and usage instructions live in the source repository linked above.