Metadata-Version: 2.4
Name: kagura-agent
Version: 0.7.1
Summary: Memory-backed autonomous agent with a Docker membrane, a Slack/Discord cockpit, and capability graduation.
Project-URL: Homepage, https://github.com/kagura-ai/kagura-agent
Project-URL: Repository, https://github.com/kagura-ai/kagura-agent
Project-URL: Issues, https://github.com/kagura-ai/kagura-agent/issues
Author: Kagura AI
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agent,ai,ai-agent,anthropic,autonomous,claude,claude-agent-sdk,llm,mcp,memory,security
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Provides-Extra: aws
Requires-Dist: boto3>=1.34; extra == 'aws'
Provides-Extra: brain
Requires-Dist: kagura-brain<0.7,>=0.6.0; extra == 'brain'
Provides-Extra: claude
Requires-Dist: claude-agent-sdk>=0.1.0; extra == 'claude'
Provides-Extra: cloudflare
Requires-Dist: httpx>=0.27; extra == 'cloudflare'
Provides-Extra: dev
Requires-Dist: anyio>=4; extra == 'dev'
Requires-Dist: genbadge[coverage]>=1.1; extra == 'dev'
Requires-Dist: mypy>=1.9; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: discord
Requires-Dist: discord-py>=2.3; extra == 'discord'
Provides-Extra: gcp
Requires-Dist: google-auth>=2.0; extra == 'gcp'
Requires-Dist: requests>=2.31; extra == 'gcp'
Provides-Extra: github
Requires-Dist: httpx>=0.27; extra == 'github'
Requires-Dist: pyjwt[crypto]>=2.8; extra == 'github'
Provides-Extra: keyring
Requires-Dist: keyring>=24; extra == 'keyring'
Provides-Extra: memory
Requires-Dist: kagura-memory<0.38,>=0.37; extra == 'memory'
Requires-Dist: mcp<2,>=1; extra == 'memory'
Provides-Extra: slack
Requires-Dist: slack-bolt>=1.18; extra == 'slack'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/kagura-ai/kagura-agent/main/docs/kagura-ai-logo.png" alt="Kagura AI" width="420">
</p>

# kagura-agent

[![CI](https://github.com/kagura-ai/kagura-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/kagura-ai/kagura-agent/actions/workflows/ci.yml)
![Coverage](https://raw.githubusercontent.com/kagura-ai/kagura-agent/main/docs/coverage.svg)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/kagura-ai/kagura-agent/blob/main/LICENSE)
![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)

**A memory-backed autonomous AI agent.** It combines a pluggable agentic brain,
[Kagura Memory Cloud](https://github.com/kagura-ai/memory-cloud), a Docker security
membrane, and a Slack/Discord cockpit. Use it from the CLI with `run`, `repl`,
`serve`, `doctor`, and `setup`.

The default brain is Claude through the
[Claude Agent SDK for Python](https://docs.claude.com/en/api/agent-sdk). The optional
[`kagura-brain`](https://github.com/kagura-ai/kagura-brain) backend adds Claude,
Codex, and Ollama-compatible providers behind the same interface.

> **Status:** alpha, package version `0.7.1`. The v0.1–v0.7 pure-Python skeleton is
> implemented and tested with strict typing and at least 95% coverage. Live Docker,
> cloud credential, and chat-transport edges remain deployment-specific.

## Why kagura-agent

- **Persistent memory:** decisions, failures, and progress survive individual runs.
- **Real hands:** filesystem, shell, Git, Docker, cloud APIs, and custom MCP tools.
- **Bounded autonomy:** credentials, mounts, and egress are granted per task.
- **Operator control:** long-running work can be launched, resumed, approved, or
  stopped from a CLI or chat cockpit.

## Quickstart

You need Python 3.11 or newer, a Kagura Memory Cloud login, and a configured brain.
The base package intentionally ships without a brain dependency.

```bash
python -m venv .venv
# Activate the virtual environment, then install the default brain:
pip install 'kagura-agent[claude]'

# Authenticate both required services:
kagura auth login
claude

# Verify the environment and run a task:
kagura-agent doctor
kagura-agent run "summarize the repository layout"
```

`ANTHROPIC_API_KEY` can replace the Claude subscription login. For the
`kagura-brain` Claude/Codex/Ollama backend, chat transports, Docker mode, Windows
activation, and first-run troubleshooting, see
[Getting started](https://github.com/kagura-ai/kagura-agent/blob/main/docs/getting-started.md).

## Main commands

| Command | Purpose |
|---|---|
| `kagura-agent run "…"` | Run one task |
| `kagura-agent repl` | Continue an interactive session |
| `kagura-agent serve --transport slack` | Start the chat cockpit |
| `kagura-agent doctor` | Check memory, brain, Docker, and provider readiness |
| `kagura-agent setup transport` | Show transport setup guidance |

## Architecture at a glance

The session layer orchestrates tasks and checkpoints without depending on a
specific model SDK. The selected brain owns its agentic tool loop; Kagura Memory
Cloud provides durable context; the host-side membrane controls filesystem,
network, and credential access.

![kagura-agent architecture](https://raw.githubusercontent.com/kagura-ai/kagura-agent/main/docs/architecture.svg)

The full rationale, provider boundary, capability model, security membrane, and
cockpit protocol live in the
[design document](https://github.com/kagura-ai/kagura-agent/blob/main/docs/design.md).

## Documentation

| Document | Contents |
|---|---|
| [Documentation index](https://github.com/kagura-ai/kagura-agent/blob/main/docs/README.md) | Map of all project documentation |
| [Getting started](https://github.com/kagura-ai/kagura-agent/blob/main/docs/getting-started.md) | Installation, authentication, commands, bootstrap, troubleshooting |
| [Design](https://github.com/kagura-ai/kagura-agent/blob/main/docs/design.md) | Scope, architecture, capabilities, security membrane, cockpit internals |
| [Project status and scope](https://github.com/kagura-ai/kagura-agent/blob/main/docs/project-status.md) | Current boundary, roadmap, repository map, milestone coverage |
| [Extending](https://github.com/kagura-ai/kagura-agent/blob/main/docs/extending.md) | Custom MCP tools, egress, credential leasing, secret handling |
| [Operations](https://github.com/kagura-ai/kagura-agent/blob/main/docs/operations.md) | Incident response and credential rotation runbooks |
| [Bootstrap evaluation](https://github.com/kagura-ai/kagura-agent/blob/main/docs/bootstrap-eval.md) | Ranking evaluation and rollout gate |
| [Legal notes](https://github.com/kagura-ai/kagura-agent/blob/main/docs/legal.md) | Open terms-of-service and operator-responsibility questions |
| [Contributing](https://github.com/kagura-ai/kagura-agent/blob/main/CONTRIBUTING.md) | Development workflow and contribution guide |
| [Security policy](https://github.com/kagura-ai/kagura-agent/blob/main/SECURITY.md) | Supported versions and vulnerability reporting |
| [Changelog](https://github.com/kagura-ai/kagura-agent/blob/main/CHANGELOG.md) | Release history |

## Development

```bash
git clone https://github.com/kagura-ai/kagura-agent.git
cd kagura-agent
pip install -e '.[dev]'
pytest
mypy
```

See
[CONTRIBUTING.md](https://github.com/kagura-ai/kagura-agent/blob/main/CONTRIBUTING.md)
for the full development workflow.

## Related repositories

| Repository | Role |
|---|---|
| [`kagura-ai/kagura-engineer`](https://github.com/kagura-ai/kagura-engineer) | Independent coding-specialized sibling agent |
| [`kagura-ai/kagura-code-reviewer`](https://github.com/kagura-ai/kagura-code-reviewer) | Review subagent used by kagura-engineer |
| [`kagura-ai/memory-cloud`](https://github.com/kagura-ai/memory-cloud) | Persistent memory backbone and MCP server |
| [`kagura-ai/kagura-memory-python-sdk`](https://github.com/kagura-ai/kagura-memory-python-sdk) | Trusted-host bootstrap SDK |

## License

[Apache License 2.0](https://github.com/kagura-ai/kagura-agent/blob/main/LICENSE) —
© 2026 Kagura AI. See
[NOTICE](https://github.com/kagura-ai/kagura-agent/blob/main/NOTICE) for attribution.
