ankaloop

<p align="center"> <img src="assets/brand/ankaloop-wordmark.svg" alt="AnkaLoop — persistent coding-agent runtime" width="700"> </p> <h1 align="center">AnkaLoop</h1> <p align="center"> <a href="https://pypi.org/project/ankaloop/"><img src="https://badge.fury.io/py/ankaloop.svg" alt="PyPI version"></a> AnkaLoop is built for developers who want a useful agent immediately, not a framework they must ## Why AnkaLoop <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache-2.0"></a> python -m pip install ankaloop <p align="center"><strong>A batteries-included, self-hostable, persistent coding-agent runtime anka init anka AnkaLoop is built for developers who want a useful agent immediately, not a framework they must assemble first. It ships with file editing, shell execution, web access, memory, skills, anka --once "summarize this repository and suggest the next test to run" automation as first-class capabilities.

The package is named ankaloop. It installs the recommended anka command and the ankaloop command. For a no-install run, use uvx ankaloop.

uvx ankaloop init

• Ready on the first run: read/search/edit files, apply patches, run commands, browse the web, uvx ankaloop pip install ankaloop cron/systemd/Kubernetes jobs. Each surface supports persistent sessions; session discovery and management are not yet identical across every surface. pip install ankaloop[telegram] compaction, progress events, and cancellation support make long-running work easier to trust.
• Extensible when you need it: add MCP servers, skills, slash commands, hooks, and custom agent specs without giving up the built-in experience.

30-second start

Requires Python 3.11+ and credentials for a supported model provider (or an OpenAI-compatible endpoint). init writes the provider configuration to ~/.config/amcp/config.toml.

# Install the PyPI package
python -m pip install ankaloop

# Configure your model provider, then start in the current project
anka init
anka

# Or run a single task
anka --once "summarize this repository and suggest the next test to run"

The package is named ankaloop. It installs the recommended anka command and the ankaloop command. For a no-install run, use uvx ankaloop.

What you get

| Area | Built-in capabilities | |------|-----------------------| | Coding loop | read_file, grep, apply_patch, write_file, bash, think, todo, task | | Research | Web search/fetch tools plus MCP server integration over stdio or HTTP/SSE | | Agent orchestration | Primary/subagent architecture with coder, explorer, planner, and focused_coder types | | Context & memory | Persistent sessions, AGENTS.md rules, smart compaction, progressive loading, searchable memory and session history | | Interfaces | CLI, FastAPI HTTP/WebSocket server, Telegram bot | | Customization | TOML config, YAML agent specs, slash commands, reusable skills, hooks, event bus | | Model support | OpenAI Chat Completions, OpenAI Responses API, Anthropic Claude, and OpenAI-compatible endpoints |

Installation

Quick Run with uvx (no install needed)

# Initialize config first (model and runtime settings)
uvx ankaloop init

# Run the agent
uvx ankaloop

From PyPI

pip install ankaloop

# With Telegram bot support
pip install ankaloop[telegram]

From Source (development)

git clone https://github.com/tao12345666333/ankaloop.git
cd anka

# Using uv (recommended); includes dependencies needed by the full test suite
uv sync --extra dev --extra telegram
source .venv/bin/activate

# Or with pip in an activated virtual environment
python -m venv .venv && source .venv/bin/activate
python -m pip install -e ".[dev,telegram]"

Usage

# Initialize config
anka init              # interactive wizard
anka init --quick      # default config without prompts

# Agent chat (default command)
anka                                    # interactive mode with conversation history
anka --once "create a hello.py file"    # single message
anka -t explorer --once "find all TODOs"  # use built-in agent type
anka --agent path/to/agent.yaml         # use custom agent spec
anka --session my-session               # use specific session ID
anka --clear                            # clear conversation history
anka --list                             # list available agent specifications
anka --list-types                       # list built-in agent types
anka --list-sessions                    # list saved sessions

# MCP server management
anka mcp tools --server custom
anka mcp call --server custom --tool example_tool --args '{"query":"rust async"}'

# HTTP/WebSocket server
anka serve                              # start on localhost:8080
anka serve --port 8080 --host 0.0.0.0   # requires [server.auth] configuration
anka serve --telegram                   # start Telegram bot alongside
anka attach http://localhost:8080       # connect to a running server
anka attach https://server.example --api-key "$ANKA_SERVER_API_KEY"

# Telegram bot
anka telegram start                     # start polling
anka telegram status                    # show config status
anka telegram setup                     # interactive setup

Built-in Tools

| Tool | Description | |------|-------------| | read_file | Read text files with slice mode (line ranges) or indentation mode (anchor-based context) | | grep | Search for patterns in files using ripgrep | | bash | Execute shell commands from the request working directory; large output is truncated | | think | Internal reasoning and planning | | todo | Manage a todo list to track tasks during complex operations | | apply_patch | Apply diff-based patches to files (see docs/apply-patch.md) | | write_file | Write content to files (for creating new small files) | | task | Spawn sub-agents for parallel task execution | | web_search | Search the web for information without configuring a search API key | | web_fetch | Fetch and extract content from web pages without configuring a search API key | | memory | Store and retrieve persistent cross-session memories | | session_search | Search persisted conversation history across sessions |

Multi-Agent System

AnkaLoop supports a Primary/Subagent architecture with built-in agent types:

| Agent Type | Mode | Description | |------------|------|-------------| | coder | Primary | Full-capability coding agent with write access | | explorer | Subagent | Read-only fast codebase exploration | | planner | Subagent | Read-only planning and analysis | | focused_coder | Subagent | Focused implementation of specific changes |

Primary agents can delegate to subagents for complex tasks. Use -t <type> to select an agent type.

Skills System

Skills are reusable knowledge or behavior definitions (markdown with YAML frontmatter) that inject specialized capabilities into the agent's system prompt. See docs/skills-and-commands.md for full documentation.

Built-in skills:

• skill-creator - Generate new skills interactively
• session-cleanup - Clean up old session files
• heartbeat - Periodic health check and status reporting
• networked-research - Multi-source web research with synthesis
• telegram-sender - Send messages via Telegram

Discovery locations (increasing precedence):

1. Built-in skills (bundled with AnkaLoop)
2. User skills: ~/.config/amcp/skills/<name>/SKILL.md
3. Home agent skills: ~/.agents/skills/<name>/SKILL.md
4. Project skills: .amcp/skills/<name>/SKILL.md

Skills support scheduled (cron) and event-based auto-triggers for autonomous execution. Hot reload is enabled when running the HTTP server.

Slash Commands

Custom command shortcuts defined as TOML files, invoked with /command syntax. Features include:

• {{args}} placeholder for command arguments
• !{shell command} for shell output injection (auto-escaped args)
• @{file path} for file content injection
• Namespaced commands via subdirectories (e.g., git/commit.toml -> /git:commit)

Discovery locations:

1. User commands: ~/.config/amcp/commands/*.toml
2. Project commands: .amcp/commands/*.toml (takes precedence)

See docs/skills-and-commands.md for details and examples/commands/ for samples.

HTTP/WebSocket Server

AnkaLoop can run as an HTTP/WebSocket server for remote access:

anka serve                    # start on localhost:8080
anka serve --port 8080        # custom port
anka serve -w /path/to/project  # set working directory
anka attach http://localhost:8080  # connect from another terminal

API endpoints (visit /docs for interactive Swagger UI):

• GET /api/v1/health - health check
• POST /api/v1/sessions - create sessions
• POST /api/v1/sessions/{id}/prompt - submit a prompt and return request status
• POST /api/v1/sessions/{id}/prompt/stream - submit a prompt and stream JSON-line events
• GET /api/v1/sessions/{id}/turns/{turn_id} - query queued, running, or retained terminal turn state
• POST /api/v1/sessions/{id}/cancel - cancel current session work
• GET /api/v1/sessions/{id}/timeline - read durable metadata-only execution events
• DELETE /api/v1/sessions/{id} - delete a session
• GET /api/v1/tools - list available tools
• GET /api/v1/agents - list agent types
• WS /ws - WebSocket for live events

Server authentication

API authentication uses one configured API key, sent as Authorization: Bearer <api-key>. Unauthenticated operation is permitted only when the server binds to a loopback address. A non-loopback bind (for example 0.0.0.0) requires authentication; configure an API key before exposing the service. This is transport authentication, so use TLS or a trusted reverse proxy for traffic that leaves the machine.

Authenticated CLI clients can pass --api-key or set ANKA_SERVER_API_KEY. HTTP clients send Authorization: Bearer <api-key>; WebSocket clients may use the same header. The health endpoint remains public for probes.

Docker

The default Docker command starts the server on loopback — safe without authentication:

docker build -t ankaloop .
docker run -it ankaloop serve          # loopback:8080, no auth needed

To expose the server on the host network, provide an API key via environment variables:

docker run -p 8080:8080 \
    -e ANKA_HOST=0.0.0.0 -e ANKA_API_KEY=your-secret \
    ankaloop serve

Alternatively, mount a config.toml with [server.auth] enabled:

docker run -p 8080:8080 -v ./config.toml:/root/.config/amcp/config.toml \
    ankaloop serve --host 0.0.0.0

The health check (GET /api/v1/health) always remains public for container orchestration probes. For interactive CLI usage inside a container without starting the server:

docker run -it ankaloop --once "explain this codebase"

Durable execution timeline

AnkaLoop stores a bounded per-session timeline beside each session snapshot. It records turn, tool, subagent task, context-compaction, provider retry/error, and token-usage metadata so interrupted sessions remain inspectable. Prompt content, tool arguments, tool output, and raw provider exception text are deliberately excluded. The newest 2,000 events are retained by default and can be queried with GET /api/v1/sessions/{id}/timeline.

Telegram Integration

AnkaLoop provides a Telegram Bot interface for remote interaction with agents. Install with pip install ankaloop[telegram].

Features:

• DM and group chat support with configurable policies (allowlist, mention, open, disabled)
• Pairing via one-time codes
• Topic/thread support in group chats
• Notification system (CI failures, PR reviews, task completions,