# ag

> ag (@elementics/ag) is a persistent, open-source AI coding agent CLI. Unlike stateless agents that re-read context on every invocation, ag maintains conversation memory across sessions using checkpoints and result references. ~130kB, zero dependencies, any model via OpenRouter or any OpenAI-compatible API.

Install: `npm install -g @elementics/ag`
GitHub: https://github.com/elementics/ag
npm: https://www.npmjs.com/package/@elementics/ag
License: Apache-2.0

## Overview

- [Home](https://ay-gee.com): Product overview, features, architecture, install guide
- [Docs](https://ay-gee.com/docs): Full reference — installation, configuration, CLI flags, REPL commands, tools, memory, permissions, skills, checkpoints, sub-agents, examples
- [Why Persistent Agents?](https://ay-gee.com/why-persistent): Article on why persistent agent state beats re-loading context each session

## Docs Sections

- [Installation](https://ay-gee.com/docs#install): `npm install -g @elementics/ag`, API key setup via `AG_API_KEY` or `AG_OPENROUTER_KEY`
- [Quick Start](https://ay-gee.com/docs#quickstart): Run `ag` in any project directory to start a session
- [Configuration](https://ay-gee.com/docs#config): `ag.config.json` — model, temperature, max tokens, tool permissions
- [CLI Flags](https://ay-gee.com/docs#cli-flags): `--model`, `--no-memory`, `--checkpoint`, `--debug` and others
- [REPL Commands](https://ay-gee.com/docs#repl-model): `/model`, `/memory`, `/plan`, `/checkpoint`, `/rewind`, `/context`, `/config`, `/tools`, `/skill`, `/content`, `/permissions`
- [Built-in Tools](https://ay-gee.com/docs#tools-reference): 14 tools — bash, file, memory, plan, git, grep, web, task, content, result, history, agent, skill, self
- [Self Tool](https://ay-gee.com/docs#tool-self): Scaffold and manage custom tools/skills/extensions via `self(action="create", type="tool", name="...")`; templates from `~/.ag/ag.md`
- [Custom Tools](https://ay-gee.com/docs#custom-tools): Define tools in `.ag/tools/` as JSON schemas + shell scripts
- [Memory System](https://ay-gee.com/docs#memory-system): Persistent key-value store across sessions via `/memory`
- [Permissions](https://ay-gee.com/docs#permissions-system): Fine-grained allow/deny rules per tool and command pattern
- [Skills](https://ay-gee.com/docs#skills-system): Reusable prompt templates; install from registry with `/skill add <name>`
- [Extensions](https://ay-gee.com/docs#extensions-system): Hook into agent lifecycle events
- [Checkpoints & Rewind](https://ay-gee.com/docs#checkpoints-rewind): Save and restore conversation/file state; `/checkpoint create`, `/rewind` with change preview
- [Loop Guards & Traces](https://ay-gee.com/docs#loop-guards): Per-turn working-state ledger, repeated-edit guard stops, JSONL traces
- [Context Compaction](https://ay-gee.com/docs#context-compaction): Automatic summarization when context approaches model limits
- [Sub-Agents](https://ay-gee.com/docs#sub-agents): Spawn parallel child agents from within a session
- [Prompt Editing](https://ay-gee.com/docs#prompt-editing): Tab completion, paste pills, keyboard shortcuts, and status footer at the prompt
- [Steering](https://ay-gee.com/docs#steering): Mid-session course correction with full editing support; late steers trigger re-request
- [Guardrails](https://ay-gee.com/docs#guardrails): Built-in safety rules; extend with custom deny patterns
- [Examples](https://ay-gee.com/docs#examples): Common workflows — refactoring, test generation, debugging, code review

## Optional

- [GitHub Issues](https://github.com/elementics/ag/issues): Bug reports and feature requests
- [npm changelog](https://www.npmjs.com/package/@elementics/ag?activeTab=versions): Version history