Documentation

Everything you need to use ag effectively.

Installation #

# Run directly, no install
npx @elementics/ag

# Global install
npm install -g @elementics/ag

Requires Node.js 20+. An API key is only needed if you're using a cloud model via OpenRouter — local models via Ollama or LM Studio work with no key at all.

Cloud models (OpenRouter)

REPL — just run ag and it will prompt you for a key on first use. To set or change it from within the REPL:

/config set apiKey sk-or-v1-...

CLI — pass the key inline:

ag -k sk-or-v1-... "your prompt here"

You can also set OPENROUTER_API_KEY in your environment — ag picks it up automatically.

Local models — no key needed, just point at your local server:

ag -b http://localhost:11434/v1 -m gemma4

# Or persist it
/config set baseURL http://localhost:11434/v1
/config set model gemma4

Quick Start #

# Interactive REPL
ag                                     # starts in plan mode

# One-shot query (auto-approves tools)
ag "what files are here?"

# Specific model
ag -m openai/gpt-4o "help me refactor this"

# Auto-approve all tool calls
ag -y "build an API with auth and tests"

# Local LLM via Ollama
ag -b http://localhost:11434/v1 -m gemma4

Configuration #

Config lives at ~/.ag/config.json. Set values via the REPL or edit the file directly.

{
  "apiKey": "sk-or-v1-...",
  "model": "anthropic/claude-sonnet-4.6",
  "baseURL": "https://openrouter.ai/api/v1",
  "maxIterations": 25,
  "tavilyApiKey": "tvly-...",
  "contextLength": 131072,
  "autoApprove": false,
  "interactionMode": "plan",
  "systemPrompt": "..."
}

CLI flags and environment variables take priority over config file values.

One-shot runs always start in auto mode. Interactive REPL sessions default to the saved interactionMode, which starts as plan.

CLI Flags #

Pattern: /noun to show, /noun subcommand to act. Type /help for the full list.

/model #

/model openai/gpt-4o
/model search claude

/memory #

/plan #

/checkpoint #

/checkpoint create before-refactor

/rewind #

Restore modes: (1) code + conversation, (2) conversation only, (3) code only, (4) cancel.

/context #

/config #

/config set contextLength 131072
/config set baseURL http://localhost:11434/v1

/tools #

List all loaded tools (built-in and custom). Custom tools are marked with +.

/skill #

/content #

/permissions #

/clear #

Alias for /memory clear. Defaults to session scope when no argument is given.

/help & /exit #

Built-in Tools #

13 tools available to the agent. Each has named actions.

self #

Manages Ag's own custom tools, skills, and extensions. Built-in tools are read-only and cannot be modified or removed.

self(action="list")
self(action="create", type="tool", name="notify", description="Send a desktop notification")
self(action="create", type="skill", name="code-review", scope="global")
self(action="disable", type="tool", name="notify")
self(action="remove", type="tool", name="notify")

Custom Tools #

Add your own tools in two ways: drop a .mjs file into ~/.ag/tools/ (global) or .ag/tools/ (project-local), or register one at runtime from an extension using agent.addTool().

File-based tool

// ~/.ag/tools/notify.mjs  (or .ag/tools/notify.mjs for project-local)
export default {
  type: "function",
  function: {
    name: "notify",
    description: "Send a desktop notification",
    parameters: {
      type: "object",
      properties: {
        message: { type: "string", description: "Notification text" }
      },
      required: ["message"]
    }
  },
  async execute({ message }) {
    // call your notification service, run osascript, etc.
    return `Notified: ${message}`;
  }
};

Tool with permission key

Add permissionKey to plug into the permissions system. ag will prompt with deploy(staging) or deploy(production) as the pattern.

// .ag/tools/deploy.mjs
export default {
  type: "function",
  function: {
    name: "deploy",
    description: "Deploy to staging or production",
    parameters: {
      type: "object",
      properties: {
        target: { type: "string", enum: ["staging", "production"] }
      },
      required: ["target"]
    }
  },
  permissionKey: { qualifier: "target" },
  async execute({ target }) {
    return `Deployed to ${target}`;
  }
};

Read-only tools (plan mode)

Custom tools are blocked in plan mode by default. Add readOnly to allow specific actions — or all — while in plan mode.

// readOnly: true allows all actions in plan mode
// readOnly: ["search", "get", "list"] allows only those actions
export default {
  type: "function",
  readOnly: ["search", "get", "list"],
  function: {
    name: "snippet",
    description: "Save and retrieve code snippets",
    parameters: { /* ... */ }
  },
  async execute({ action }) { /* ... */ }
};

Read-only custom tools also skip the permission prompt, just like built-in read-only tools.

Runtime tool via extension

Register a tool from an extension using agent.addTool(). Useful when the tool needs access to agent state or dynamic config.

// .ag/extensions/dynamic-tool.ts
export const name = 'dynamic-tool';
export const description = 'Registers a custom tool at startup';

export default (agent) => {
  agent.addTool({
    type: 'function',
    function: {
      name: 'ping',
      description: 'Ping a host and return latency',
      parameters: {
        type: 'object',
        properties: { host: { type: 'string' } },
        required: ['host']
      }
    },
    execute: async ({ host }) => {
      // your implementation
      return `pong from ${host}`;
    }
  });
};

Memory System #

Three-tier memory, all stored as plain markdown you can read and edit directly.

Memory is injected into every API call as part of the system prompt. The agent writes via the memory tool; you can also edit the files directly.

File layout

~/.ag/
  config.json
  memory.md               # global memory
  skills/                  # global skills
  tools/                   # global custom tools
  projects/<id>/
    memory.md             # project memory
    plans/                # timestamped plan files
    tasks.json            # task tracking
    history.jsonl         # conversation history
    session-state.json    # session resume context
    content/              # cached images and PDFs
    results/              # cached tool results
    checkpoints/          # checkpoint metadata
    shadow/               # local shadow repo for snapshots
    traces/               # JSONL run traces

Permissions #

Three-scope rule system using glob patterns. Deny rules always override allow rules.

Pattern syntax

Tool(qualifier:glob)

# Examples
bash(npm:*)           # any bash command starting with npm
bash(git:*)           # any bash command starting with git
file(write:src/**)    # file writes under src/
file(edit:*)          # all file edits
git(commit)           # git commits only
web(fetch:*github*)   # fetch from GitHub domains
bash(*)               # all bash commands
*                     # everything

Prompt options

When ag asks for permission, you can respond:

Always allowed (no prompt)

file(read), file(list), grep(*), memory(*), plan(*), skill(*), git(status), web(fetch), web(search), task(*), agent(*), content(*), result(*), history(*)

Built-in web fetch and search are treated as read-only. In plan mode they stay available for research, while file edits, bash, and sub-agent spawning remain blocked until you switch to auto.

Skills #

Skills are reusable SKILL.md files with YAML frontmatter. Place them in ~/.ag/skills/ (global) or .ag/skills/ (project-local). Local overrides global.

---
name: frontend
description: Frontend development with React and Tailwind
tools: true     # loads adjacent tools.mjs
always: true    # always inject into context
---

Your skill instructions go here...

# Browse and install from registry
/skill search frontend
/skill add elementics/frontend

# Or drop a file manually
mkdir -p .ag/skills && vim .ag/skills/SKILL.md

All skills are scanned by guardrails at load time. Blocked if they contain prompt injection patterns.

Extensions #

TypeScript files in .ag/extensions/ (project) or ~/.ag/extensions/ (global) that hook into the agent's lifecycle.

// .ag/extensions/logger.ts
export const name = 'logger';
export const description = 'Log all tool calls';

export default (agent) => {
  agent.on('tool_call', (e) => {
    console.log(`Tool: ${e.toolName}`);
  });
};

Lifecycle events

Fields marked † are writable — mutations affect agent behavior.

Checkpoints & Rewind #

Checkpoints are created automatically at every turn start using a local shadow repo. This captures all file changes — including those from bash commands like npm install, build scripts, or sed. The user's .git is never touched.

# List all checkpoints
/checkpoint

# Create a named checkpoint
/checkpoint create before-refactor

# Rewind interactively
/rewind

# Quick rewind to most recent
/rewind last

/checkpoint lists newest first. Before /rewind asks for a restore mode, ag shows a diff stat preview of code changes since the selected checkpoint. Four restore modes: restore code + conversation, conversation only, code only, or cancel. Extensions can intercept via the checkpoint_restore event. Git is required for checkpoints — a warning is shown at startup if unavailable.

Loop Guards & Traces #

During each turn, ag keeps a compact working-state ledger of files changed, file reads, verification commands, and guard decisions. If the agent tries to edit or write the same file more than three times without reading it or running verification, ag stops the turn instead of continuing a blind edit loop.

Per-session JSONL traces are written under ~/.ag/projects/<id>/traces/. ag keeps the latest 20 trace files, removes files older than 14 days, and rotates active trace files after 10MB.

Context Compaction #

At 90% of the configured context window, ag automatically summarizes older interactions to free space. The original user request is always preserved, and a context reconstruction message is injected after compaction with the active plan and recent files. Older tool outputs from non-recent turns are masked to save space (the agent can retrieve them on demand). A rolling window of the last 10 user messages is maintained in the system prompt across sessions. System prompt, tools, and skills are never compacted.

/context
Context Window
  Estimated:  ~4.4K tokens
  Window:     4.4K/262K (2%)

Breakdown
  ██████████████████████████████████████████████████  ~4.4K/262K (2%)

  █ System prompt      23%  ~1.0K
  █ Environment        <1%  ~18
  █ Global memory       1%  ~51
  █ Skill catalog      11%  ~464
  █ Tool definitions   61%  ~2.7K
  █ Custom tools        3%  ~127
  █ Interactions        1%  ~47

# Force compaction
/context compact

# Set context length for local models
/config set contextLength 131072

Context window size is auto-detected for OpenRouter models. For local LLMs, set it manually.

Sub-Agents #

Spawn independent agents that run in parallel. Each gets project memory, plans, skills, tools, and extensions but a clean conversation context.

# Ask the agent to research in parallel
you> Research auth best practices and set up the database schema
      at the same time

# Or specify a cheaper model for sub-agent work
you> Research this using claude-haiku

Depth limit is 1 — sub-agents cannot spawn sub-sub-agents. Sub-agents can link to tasks for progress tracking.

Prompt Editing #

The you> prompt has built-in line editing, tab completion, and paste handling. A status footer shows mode, model, context usage, tokens, cost, and turn number while the prompt is active.

Keyboard Shortcuts

Tab Completion

Tab completes in priority order. Single match completes inline. Multiple matches show a candidate row; press Tab to cycle forward, Shift+Tab to cycle backward.

you> /mo         ← Tab → /model (slash commands)
you> /config s   ← Tab → /config set (subcommands)
you> /config set ba ← Tab → /config set baseURL (config keys)
you> /model cla  ← Tab → model names from cached list
you> src/cli/re  ← Tab → src/cli/repl.ts (file paths)

Paste Pills

Pasting long text (≥ 200 characters or ≥ 3 lines) shows a compact pill instead of inline text:

you> [Pasted 18 lines]

The real content is sent when you press Enter. Backspace deletes the whole pill. You can type before or after a pill on the same line.

Status Footer

While the prompt is active, a footer shows at the bottom of the terminal:

claude-sonnet-4-6 | ███◻◻◻◻◻ 12% | ↑3.2K ↓1.1K | $0.04 | turn 3

The footer disappears when you press Enter. Use /context for a detailed breakdown.

Steering #

Press Tab while the agent is working to open a steer> prompt. The steer prompt has the same editing features as the main prompt — paste pills, Ctrl+U/W, and keyboard shortcuts. Output is buffered while you type.

you> build an API with auth
  ⠇ [bash] npm init...
                         ← press Tab
  steer> use PostgreSQL not SQLite
                         ← press Enter, agent adjusts

Steer messages are injected before the next LLM call. If the agent has already finished its response, the response is discarded and re-requested with your correction applied.

Guardrails #

All externally loaded tools and skills are scanned at load time across 5 threat categories.

Dangerous bash commands (rm -rf /, fork bombs, sudo rm, pipe-to-shell) are always blocked before execution regardless of permissions.

Examples #

Local LLM via Ollama

ag -b http://localhost:11434/v1 -m gemma4 "hello"

# Set permanently
/config set baseURL http://localhost:11434/v1
/config set contextLength 131072

Git workflow with memory

you> save to project memory: Current ticket: JIRA-123.
     PR template: ## What\n## Why\n## Testing

you> create a branch for this ticket and start working

Background dev server

you> start the dev server in the background and
     tell me when it's ready

[bash] npm run dev (background) → PID 12345
[bash] output PID 12345 → "ready on :3000"

Parallel sub-agents

you> in parallel: research auth best practices,
     set up the database schema, and write unit tests

[agent] spawning 3 sub-agents...

Managing permissions

# When prompted:
? bash: npm test  y/n  a=always  p=project  d=deny  D=deny project
> a
+ Session rule: bash(npm:*)

# Or set rules directly
/permissions allow bash(npm:*)
/permissions deny bash(rm:*)
/permissions save

Attaching images

# From file
/content add screenshot.png
you> what's wrong with this UI?

# From clipboard
/content paste

# Screen capture
/content screenshot

Session resume

# ag saves session state automatically
# just start ag in the same directory to resume
ag
Resumed session (5 minutes ago) — 3 tasks pending
  > build-auth-module  ~/.ag/projects/abc123/plans/build-auth-module.md

Context management

# Check how much context you're using
/context
Context Window
  Estimated:  ~4.4K tokens
  Window:     4.4K/262K (2%)

Breakdown
  ██████████████████████████████████████████████████  ~4.4K/262K (2%)

  █ System prompt      23%  ~1.0K
  █ Environment        <1%  ~18
  █ Global memory       1%  ~51
  █ Skill catalog      11%  ~464
  █ Tool definitions   61%  ~2.7K
  █ Custom tools        3%  ~127
  █ Interactions        1%  ~47

# Force compaction if running low
/context compact