Architecture
Ailiv Agent internals — major subsystems, execution paths, data flow, and where to read next
ACP Internals
How the ACP adapter works: lifecycle, sessions, event bridge, approvals, and tool rendering
Adding Tools
How to add a new tool to Ailiv Agent — schemas, handlers, registration, and toolsets
Agent Loop Internals
Detailed walkthrough of AIAgent execution, API modes, tools, callbacks, and fallback behavior
Creating Skills
How to create skills for Ailiv Agent — SKILL.md format, guidelines, and publishing
Contributing
How to contribute to Ailiv Agent — dev setup, code style, PR process
Provider Runtime Resolution
How Ailiv resolves providers, credentials, API modes, and auxiliary models at runtime
Adding Providers
How to add a new inference provider to Ailiv Agent — auth, runtime resolution, CLI flows, adapters, tests, and docs
Prompt Assembly
How Ailiv builds the system prompt, preserves cache stability, and injects ephemeral layers
TUI & Desktop from Worktrees
Run the Ink TUI and Electron desktop app from a git worktree without a full npm install per checkout
Gateway Internals
How the messaging gateway boots, authorizes users, routes sessions, and delivers messages
Extending the CLI
Build wrapper CLIs that extend the Ailiv TUI with custom widgets, keybindings, and layout changes
Memory Provider Plugins
How to build a memory provider plugin for Ailiv Agent
Programmatic Integration
Three protocols for driving ailiv-agent from external programs: ACP, the TUI gateway JSON-RPC, and the OpenAI-compatible HTTP API
Adding a Platform Adapter
This guide covers adding a new messaging platform to the Ailiv gateway. A platform adapter connects Ailiv to an external messaging service (Telegram, Discord, WeCom, etc.) so users can interact with the agent through that service.
Context Engine Plugins
How to build a context engine plugin that replaces the built-in ContextCompressor
Secret Source Plugins
How to build a secret-manager backend plugin for Ailiv Agent
Tools Runtime
Runtime behavior of the tool registry, toolsets, dispatch, and terminal environments
Model Provider Plugins
How to build a model provider (inference backend) plugin for Ailiv Agent
Cron Internals
How Ailiv stores, schedules, edits, pauses, skill-loads, and delivers cron jobs
Image Generation Provider Plugins
How to build an image-generation backend plugin for Ailiv Agent
Plugin LLM Access
Run any LLM call from inside a plugin via ctx.llm — chat or structured, sync or async. Host-owned auth, fail-closed trust gate, optional JSON Schema validation.
Video Generation Provider Plugins
How to build a video-generation backend plugin for Ailiv Agent
Web Search Provider Plugins
How to build a web-search/extract/crawl backend plugin for Ailiv Agent
Browser Provider Plugins
How to build a cloud browser backend plugin for Ailiv Agent
Egress proxy internals
How the iron-proxy egress firewall integrates with Ailiv — module layout, lifecycle, security invariants, and extension points
CLI Internals
How ailiv_cli is shaped: slash dispatch, config loaders, the skin engine, the transactional update pipeline, and process-identity rules
Browser CDP Supervisor
How Ailiv detects and responds to native JS dialogs and interacts with cross-origin iframes via a persistent CDP connection.
Codebase Ownership Map
Which directories belong to which subsystem, and where the right docs entry point lives for each
Completion backlogs
Interactive surfaces coalesce consecutive background-process completions that are
Context Compression and Caching
Ailiv Agent uses a dual compression system and Anthropic prompt caching to
Desktop Plugin SDK
Extend the native Ailiv Desktop app — panes, pages, sidebar nav, status bar, palette commands, keybinds, themes, and a scoped backend namespace, with one import and no build step.
Build a Plugin
Step-by-step guide to building a complete Ailiv plugin with tools, hooks, data files, and skills
Session Storage
Ailiv Agent uses a SQLite database (~/.ailiv/state.db) to persist session
Subagent lifecycle API
Plugins can launch and supervise fresh Ailiv child sessions without importing
Terminal Environment Provider Plugins
Ailiv runs shell commands through a pluggable set of terminal backends.
Trajectory Format
Ailiv Agent saves conversation trajectories in ShareGPT-compatible JSONL format