Metadata-Version: 2.3
Name: tachikoma-agent
Version: 1.0.0
Summary: A proactive personal assistant built on Claude Agent SDK
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Dist: claude-agent-sdk
Requires-Dist: pydantic
Requires-Dist: prompt-toolkit
Requires-Dist: rich
Requires-Dist: tomlkit
Requires-Dist: sqlalchemy[asyncio]>=2.0
Requires-Dist: aiosqlite>=0.20
Requires-Dist: alembic>=1.13
Requires-Dist: loguru>=0.7
Requires-Dist: aiogram>=3.20
Requires-Dist: telegramify-markdown>=1.0
Requires-Dist: cyclopts
Requires-Dist: python-frontmatter
Requires-Dist: bubus>=1.5.6
Requires-Dist: cronsim>=2.6
Requires-Dist: watchfiles>=0.20
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/asermax/tachikoma
Project-URL: Repository, https://github.com/asermax/tachikoma
Project-URL: Issues, https://github.com/asermax/tachikoma/issues
Description-Content-Type: text/markdown

# Tachikoma

A proactive personal assistant built on [Claude Agent SDK](https://github.com/anthropics/claude-code-sdk-python) that remembers, learns, and takes initiative. Named after the think-tanks from Ghost in the Shell — curious, connected, and developing a unique personality through accumulated experience.

## Overview

Unlike traditional AI assistants that are stateless and reactive, Tachikoma maintains persistent memory across conversations, extracts learnings automatically, and processes background tasks during idle time — all accessible through a simple chat interface.

**Key capabilities (planned):**

- **Contextual conversations** — past interactions inform future ones through automatic memory retrieval
- **Memory extraction** — learns facts, preferences, and patterns from conversations without explicit user action
- **Proactive task processing** — queues and executes background tasks during idle time
- **Delegation architecture** — coordinator agent delegates specialized requests to focused sub-agents

## Requirements

- Python 3.12+
- [uv](https://docs.astral.sh/uv/)

## Installation

```bash
uv tool install tachikoma
```

### Prerequisites

- [uv](https://docs.astral.sh/uv/getting-started/installation/) installed
- Python 3.12 or later
- An [Anthropic API key](https://console.anthropic.com/)

### First Run

```bash
# Set your API key
export ANTHROPIC_API_KEY="your-key-here"

# Run the agent (starts with REPL channel by default)
tachikoma

# Or explicitly use the run subcommand
tachikoma run

# Use Telegram channel instead
tachikoma run --channel telegram
```

On first run, Tachikoma auto-generates its configuration file at `~/.config/tachikoma/config.toml`.

### Upgrading

```bash
uv tool upgrade tachikoma
```

## Development

[just](https://github.com/casey/just) is used as a task runner for common development commands.

```bash
# Clone the repository
git clone https://github.com/asermax/tachikoma.git
cd tachikoma

# Install dependencies
just install

# Run the agent
just run

# Run tests
just test

# Run linting
just lint

# Format code
just fmt

# Type checking
just typecheck

# Run all quality gates (lint + typecheck + test)
just check
```

## Status

Early development (v0.1.0). See [VISION.md](docs/planning/VISION.md) for the full project vision and [DELTAS.md](docs/planning/DELTAS.md) for the feature inventory.

## License

[MIT](LICENSE)
