ankaloop

---

AnkaLoop is for developers who want a useful coding agent now—not another framework to assemble. It combines a capable tool loop, persistent context, multi-agent delegation, skills, memory, MCP, hooks, and automation in one Python package that you can run locally or self-host.

python -m pip install ankaloop
# or: uv tool install ankaloop
anka init
anka

Why AnkaLoop

• Useful on the first run — read, search, edit, patch, and execute code with built-in tools.
• Persistent by design — sessions, searchable history, project rules, and long-term memory survive beyond a single prompt.
• One runtime, multiple surfaces — use the same agent from the CLI, an HTTP/WebSocket server, or Telegram.
• Built for real tasks — context compaction, progress events, cancellation, bounded tool use, and provider retries make long-running work observable and controllable.
• Multi-agent without plumbing — delegate focused work to built-in explorer, planner, and coder agents.
• Open and extensible — add MCP servers, reusable skills, slash commands, hooks, and custom agent specifications without replacing the built-in experience.
• Provider-flexible — connect to OpenAI, Anthropic, GMI, or any OpenAI-compatible endpoint.

Quick start

AnkaLoop requires Python 3.11+ and credentials for a supported model provider.

Install from PyPI

# Install the latest stable release (with pip)
python -m pip install ankaloop

# Or install with uv
uv tool install ankaloop

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

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

The package installs both anka (recommended) and ankaloop commands.

Run without installing

uvx ankaloop init
uvx ankaloop

Install optional Telegram support

python -m pip install "ankaloop[telegram]"
# or: uv tool install "ankaloop[telegram]"
anka telegram setup

What is included

Area	Capabilities
Coding loop	File reading and search, patching and writing, shell execution, planning, todos, and subagent tasks
Context	Persistent sessions, AGENTS.md rules, progressive loading, and smart compaction
Memory	Durable facts, episodic history, persona files, and full-text session search
Agents	Built-in coder, explorer, planner, and focused_coder roles
Interfaces	Rich terminal UI, FastAPI HTTP/WebSocket server, and Telegram bot
Research	Built-in web search/fetch plus MCP integration over stdio and HTTP/SSE
Extensions	Skills, slash commands, hooks, custom YAML agent specs, and an event bus
Automation	Cron-compatible jobs for systemd, Kubernetes, and external schedulers
Observability	OpenTelemetry traces (GenAI semantic conventions) for turns, model calls, tools, hooks, and subagents

How it fits together

 CLI ───────────────┐
 HTTP / WebSocket ──┼──▶ Agent runtime ──▶ Tools / MCP ──▶ Your project
 Telegram ──────────┘         │
                              ├── Sessions & memory
                              ├── Skills & project rules
                              └── Subagents

All interfaces use the same core runtime. Conversation state is persistent, while project rules, skills, and memory provide context across requests.

Usage

# Chat and one-shot tasks
anka
anka --once "create a hello.py file"
anka -t explorer --once "find all TODO comments"
anka --agent path/to/agent.yaml

# Sessions and agents
anka --session my-session
anka --list-sessions
anka --list-types
anka --clear

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

# Server and remote client
anka serve
anka attach http://localhost:8080

# Telegram
anka telegram setup
anka telegram start

Run anka --help or anka <command> --help for the complete command reference.

Configuration

Run anka init for the interactive provider wizard. Configuration lives in ~/.config/ankaloop/config.toml. Set ANKA_CONFIG_DIR_NAME=amcp to keep the legacy ~/.config/amcp/ path from pre-rebrand deployments.

OpenAI-compatible endpoint

[chat]
active_provider = "primary"

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

Keep credentials out of version control and provide the key through the environment:

export OPENAI_API_KEY="your-api-key"
anka --once "explain the architecture of this repository"

You can define multiple [chat.providers.<name>] profiles. Telegram administrators can list them with /models and switch the active profile with /model use <name>.

[chat]
request_timeout_seconds = 120
max_retries = 2
retry_base_delay_seconds = 0.5
# Reasoning effort for models that support it:
# none | minimal | low | medium | high | xhigh | max (unset or "auto" = provider default).
# Can also be set per provider profile or through ANKA_REASONING_EFFORT.
reasoning_effort = "high"
# Keep model reasoning on a separate channel (default): stream APIs emit `reasoning`
# frames and responses carry `reasoning_content`. Set true to restore the legacy
# behavior of folding reasoning into the message content.
reasoning_as_content = false
# Replay each assistant message's reasoning_content in conversation history.
# Off by default: providers ignore a replayed reasoning trace, so sending it only
# inflates prompt tokens. Enable (usually per provider profile) only for providers
# that reject requests lacking it.
requires_reasoning_echo = false
tool_loop_limit = 300
bash_tool_limit = 100
default_max_lines = 400
mcp_tools_enabled = true
write_tool_enabled = true
edit_tool_enabled = true
sync_tool_settle_timeout_seconds = 2.0
default_agent = "coder"

[context]
progressive_tools = true
progressive_skills = true
response_ratio = 0.30

This is the beginning of the README. Read the rest at the original. Read the full README ↗