# Auggy

> Auggy is a small Bun and TypeScript runtime for building self-hosted agents from composable augments.

The kernel runs model turns and validated tools. Augments add memory, context, transports, skills, policy, integrations, and other capabilities around those turns. Start with a working agent and install only what it needs.

This file is an index for coding agents and search/answer agents. Every curated docs page below links to its markdown version. The same set in one file is at https://auggy.dev/llms-full.txt.

## Key Docs

### Start

- [1. Run an agent](https://auggy.dev/docs/quickstart/markdown): Published. Create a local Auggy agent and complete the first model turn.
- [2. Add an augment](https://auggy.dev/docs/add-augment/markdown): Published. Install layeredMemory, inspect what the CLI adds, and verify peer-scoped memory in Console.
- [3. Build an augment](https://auggy.dev/docs/build-augment/markdown): Published. Build one project-specific typed tool inside a custom augment.
- [4. Deploy and verify](https://auggy.dev/docs/deploy/markdown): Published. Deploy the agent to Railway and verify its health, route, console, and application client.

### Runtime

- [How Auggy works](https://auggy.dev/docs/architecture/markdown): Published. How Auggy's small turn kernel and composable augments form a self-hosted agent runtime.
- [Tools](https://auggy.dev/docs/add-tools/markdown): Published. Expose typed actions the model can select during a turn and your code executes.
- [Skills](https://auggy.dev/docs/add-skills/markdown): Published. Teach the model when and how to use an augment without loading every instruction into context on every turn.
- [Memory and knowledge](https://auggy.dev/docs/memory-and-knowledge/markdown): Published. Use memory for persistent peer and agent context, and knowledge for read-only reference sources.
- [Model providers](https://auggy.dev/docs/engines/markdown): Published. Configure the model provider Auggy's kernel calls each turn.
- [Transports](https://auggy.dev/docs/transports/markdown): Published. Expose the agent over web chat, AG-UI, Telegram, and other inbound surfaces.
- [Connect MCP servers](https://auggy.dev/docs/mcp/markdown): Published. Bridge local or remote MCP server tools into Auggy with deploy-aware policy.

### Augments

- [Browse all augments](https://auggy.dev/docs/augments/markdown): Published. Understand how built-in and custom augments add capabilities to an Auggy agent.

### Operate

- [Console](https://auggy.dev/docs/console/markdown): Published. Test the running agent and inspect its capabilities, caller contexts, tool calls, and live runtime configuration.
- [Logs and recovery](https://auggy.dev/docs/logs-and-recovery/markdown): Published. Use Auggy and Railway diagnostics to recover from deploy, boot, route, and runtime failures.
- [Security](https://auggy.dev/docs/security/markdown): Published. Auggy's security boundaries, the prompt-injection threat model, and how to report a vulnerability privately.

### Advanced Preview

- [Optional app integration](https://auggy.dev/docs/engineering-patterns/markdown): Preview. Advanced preview routes, generated clients, webhooks, and delegated authorization for agents that need a small deterministic application boundary.

### Reference

- [CLI reference](https://auggy.dev/docs/cli-reference/markdown): Published. Common Auggy CLI commands for creating, extending, and operating agents.
- [agent.yaml](https://auggy.dev/docs/agent-yaml/markdown): Published. Configure identity, engine, and enabled augment order for an agent project.
- [defineAugment](https://auggy.dev/docs/define-augment/markdown): Published. Define a runtime capability that contributes tools, context, memory, transports, lifecycle, or policy to an agent.
- [defineTool](https://auggy.dev/docs/define-tool/markdown): Published. Define a typed model-callable function with validation and optional authorization requirements.
- [Changelog](https://auggy.dev/docs/changelog/markdown): Published. Latest published runtime and CLI updates.

## Machine-Readable API

- https://auggy.dev/api-reference.json: exported symbols, route options, config files, CLI commands, and the generated-client contract, each with signatures and a release status.

## Feature Status

- Published: Turn kernel, custom augments, typed tools, skills, web transport, Console, and Railway deploy. Available in the latest npm baseline (0.5.0).
- Published: Memory, knowledge, MCP, AgentMail, Telegram, visitor recognition, and notifications. Available in the npm 0.5.0 baseline, including AgentMail inbound, reply/forward, durable recovery, outbound review, and Svix verification.
- Preview: Augment HTTP routes, route manifests, OpenAPI export, generated clients, webhooks, and delegated app authorization. Usable optional app-integration surfaces, but not part of the default project or primary product promise.
- Preview: bash, budgets, link. Implemented enough to experiment with, but intentionally behind explicit setup or confirmation.

## Current Product Shape

- Runtime: Bun and TypeScript.
- Package: auggy on npm.
- Core project file: agent.yaml is the runtime source of truth for an agent project.
- Identity file: identity.md is stable operator-authored identity and policy context.
- Skills: skills/ contains trust-filtered teaching files. The model receives a compact manifest and reads a matching SKILL.md on demand before answering in that domain.
- Knowledge: knowledge/ contains read-only reference sources installed by the knowledge augment.
- State: data/ contains durable augment and runtime state such as SQLite files.
- Secrets: .env or provider-owned systems, not prompt-visible docs.
- Trust levels today: creator, agent, and public.

## Stable Built-In Augments

- fileMemory: loads identity.md and creator-approved agent-global learned-behaviors.md into context. Default learned writes require a runtime-verified creator and explicit PERSISTED confirmation.
- filesystem: gives the agent scoped file access.
- webTransport: serves chat, console, health, home, and AG-UI turn endpoints.
- webFetch: lets the agent fetch URLs and HTTP APIs.
- turnControl: lets the agent pause and ask for clarification.
- knowledge: installs local markdown and API-backed knowledge sources.
- layeredMemory: stable opt-in peer memory backed by SQLite. Explicit writes use memory_write({ topic, content }); CLI installs keep automatic extraction off by default, and cross-session continuity requires a stable recognized peer identity.
- visitorAuth: provides visitor magic-link sign-in.
- notify: sends outbound notifications to an operator or service.
- agentMail: 0.5.0 provides policy-gated send, reply, and forward tools; polling/WebSocket/Svix inbound; durable catch-up and recovery; and creator-reviewed outbound actions.
- telegramTransport: supports bidirectional Telegram chat.
- mcp: connects local or remote MCP servers.

## Advanced Preview App Integration

Custom augments may optionally expose focused deterministic HTTP routes for a frontend, webhook, or server integration. This is an advanced preview surface, not a requirement for a normal Auggy project and not a replacement for an application's primary backend.

- Use a route when software already knows the exact operation it needs.
- Use a tool when the model should mediate the operation during a turn.
- Routes and tools do not need to duplicate each other.

The preview includes augment routes, route groups, schemas, response helpers, body caps, timeouts, rate limits, route manifests, OpenAPI export, generated TypeScript clients, visitor tokens, external auth assertions, webhook policy metadata, Stripe and Svix signature verification, and delegated authorization.

## Auth And Authorization

- Runtime authentication and authorization are deterministic transport/runtime decisions.
- The model does not decide who is authorized.
- Apps using Clerk, Supabase Auth, Auth0-style middleware, or custom sessions can mint short-lived Auggy auth assertions with explicit scopes and grants.
- Auggy enforces route and tool access from those assertions.

## Docs Authority

Use this order when Auggy docs appear to disagree:

1. Public docs pages and their status labels describe the supported surface.
2. Feature Status distinguishes Published and Preview behavior.
3. Examples and guides should be treated as implementation patterns only when they match the current status labels.
4. Preview pages describe usable surfaces that may change before 1.0.

## Status Notes

- Latest published release: 0.5.0.
- Auggy is turn-oriented today; it is not a durable workflow engine or persistent job queue.
- Pin exact versions for production work until 1.0.0.