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

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

Multi-Agent System

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

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, error alerts)
• Webhook and polling modes
• Rate limiting, session timeout, typing indicators, and bounded per-session queues
• Shared slash commands including /new, /session list, /session switch <id>, /clear, and /cancel
• /new creates a fresh session and abandons the previous Telegram session's active work and queued messages

Configure via anka telegram setup or in config.toml under [telegram].

Memory System

AnkaLoop maintains persistent cross-session context using complementary memory layers:

• MEMORY.md: Curated long-term facts, preferences, and knowledge
• HISTORY.md: Append-only activity and decision history
• memory.db: Durable facts and episodic events with SQLite FTS5 search
• SOUL.md / IDENTITY.md: Optional global persona and identity guidance

Memory is stored at:

• User-level: ~/.config/amcp/memory/
• Project-level: .amcp/memory/ (project-specific knowledge)
• Global persona: ~/.config/amcp/SOUL.md and ~/.config/amcp/IDENTITY.md

The memory tool manages durable knowledge, while session_search searches persisted
conversation history. User and project memory are merged for context; persona files remain
global so the agent keeps one identity across interfaces and projects.

Hooks System

AnkaLoop provides a flexible hooks system to extend and customize agent behavior. Hooks can:

• Validate and modify tool inputs before execution
• Process tool outputs after execution
• Block dangerous operations
• Log and audit agent activities

Create .amcp/hooks.toml in your project:

[hooks.PreToolUse]
[[hooks.PreToolUse.handlers]]
matcher = "write_file|apply_patch"
type = "python"
script = "./scripts/validate-writes.py"
timeout = 30

[[hooks.PostToolUse.handlers]]
matcher = "*"
type = "command"
command = "echo 'Tool executed' >> /tmp/tool_log.txt"

See docs/hooks.md for full documentation.

Config

The CLI loads configuration from ~/.config/amcp/config.toml. Generate a starter config:

anka init

Chat Configuration

[chat]
active_provider = "primary"    # optional: selected [chat.providers.<name>] profile
request_timeout_seconds = 120
max_retries = 2                 # transient connection, timeout, 429, and 5xx failures only
retry_base_delay_seconds = 0.5  # exponential backoff with jitter
mcp_tools_enabled = true
write_tool_enabled = true
edit_tool_enabled = true
tool_loop_limit = 300
bash_tool_limit = 100
default_max_lines = 400
read_roots = ["."]                # optional: restrict read_file to these roots
default_agent = "coder"        # optional: coder, explorer, planner, focused_coder
max_queue_size = 100

[chat.providers.primary]
api_type = "openai"
base_url = "https://example.com/v1"
model = "provider/model-name"

[chat.providers.backup]
api_type = "anthropic"
model = "claude-model-name"

Telegram can switch configured providers without calling the LLM:

• /models lists configured provider profiles.
• /model use backup switches active_provider and persists it to config.toml (admin only).

Anthropic Claude:

[chat]
api_type = "anthropic"
model = "claude-model-name"

Anthropic support is included in the base ankaloop package; no separate extra is required.

MCP Servers

# HTTP/SSE transport
[servers.custom]
url = "https://example.com/mcp"

# stdio transport
[servers.local]
command = "npx"
args = ["-y", "@some/mcp-server"]

Configured MCP servers are exposed as mcp__<server>__<tool> tools. Server and
tool names are sanitized into [A-Za-z][A-Za-z0-9_-]*, because some providers
(for example Kimi/Moonshot) reject any other function name with HTTP 400. The
built-in web_search and web_fetch tools are available separately and work
out of the box without adding a search MCP server.

Context Optimization

[context]
progressive_tools = true       # dynamically load tools based on relevance
progressive_skills = true      # dynamically load skills based on relevance
response_ratio = 0.30          # reserve 30% of context for response

Server Configuration

[server]
host = "127.0.0.1"
port = 8080

[server.auth]
enabled = false              # valid without a key only for loopback binds
# api_key = "replace-with-a-secret"

For a non-loopback host, set enabled = true and api_key, then send the key as a Bearer token.

Provider and deployment options

Deploy AnkaLoop on GMI Cloud.
New GMI Cloud users can optionally sign up with the maintainer's
referral link (a referral, not a requirement).

Telegram Configuration

[telegram]
enabled = false
allowed_users = [123456789]
admin_users = [123456789]
dm_policy = "allowlist"        # "allowlist", "pairing", "open", "disabled"
group_policy = "mention"       # "mention", "open", "allowlist", "disabled"
max_queue_size = 20
typing_indicator = true

[telegram.pairing]
enabled = true
code_ttl_seconds = 1800

The Telegram runtime also supports group-specific and topic-specific policy overrides under
[telegram.groups."<chat_id>"] and [telegram.groups."<chat_id>".topics."<topic_id>"].

Development

Setup

uv sync --extra dev --extra telegram
source .venv/bin/activate
uv tool install pre-commit
pre-commit install

# Or use pip in an activated virtual environment
python -m pip install -e ".[dev,telegram]"
python -m pip install pre-commit
pre-commit install

Running Tests

make test          # run all tests
make test-cov      # run with coverage
python -m pytest -q -m "not llm"  # CI-equivalent suite without live provider calls
python -m pytest tests/test_tools.py -v  # specific test

Code Quality

make lint          # ruff check
make format        # ruff format
make type-check    # mypy

CI runs Ruff and the non-llm test suite on Python 3.11, 3.12, and 3.13. Tests marked llm
call live model providers and require credentials.

See CONTRIBUTING.md for detailed development guidelines.

Notes

• rg (ripgrep) must be installed and on PATH for the grep tool.
• MCP servers must be installed separately and runnable (stdio transport).
• Foreground tool-loop model calls classify provider failures and retry transient connection,
  timeout, rate-limit, and server errors with bounded exponential backoff. Authentication,
  invalid-request, protocol, and streaming failures after output has started are not retried.
  Compaction and memory-maintenance model calls currently retain their existing provider behavior.
• Tool-call guardrails include per-request bash limits, output truncation for bash, and
  per-conversation plus per-session read_file limits.

License

Apache-2.0