Metadata-Version: 2.4
Name: kittychain
Version: 1.0.1
Summary: Terminal agent for onchain analysis
Project-URL: Homepage, https://github.com/yejiming
Author-email: Jimmy Ye <jiming_ye@163.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,blockchain,crypto,web3
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.84.0
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: certifi>=2024.0.0
Requires-Dist: openai>=1.0
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: pyvis>=0.3.2
Requires-Dist: requests>=2.31
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

English | [中文](README_CN.md)

# KittyChain - Terminal agent for onchain analysis

KittyChain is a lightweight terminal AI agent focused on practical onchain investigation workflows. It combines a compact interactive CLI with built-in tools for wallet inspection, token analysis, web lookup, local file operations, and skill-based task guidance, so you can move from a question to an actionable chain analysis session in one place.

![KittyChain home screenshot](docs/assets/kittychain-home.png)

## Get Started

1. Install KittyChain:

```bash
pip install kittychain
```

2. Start the guided configuration flow:

```bash
kittychain --config
```

3. Launch the interactive terminal UI:

```bash
kittychain
```

For coding work, start the coding-focused toolset:

```bash
kittychain --code
```

## Features And Onchain Capabilities

- Lightweight terminal agent loop with an interactive REPL and one-shot prompt mode.
- Support for OpenAI-compatible and Anthropic-compatible model interfaces.
- Built-in local tools for shell execution, file reading and editing, web search, web fetching with LLM summaries, TODO tracking, and skill loading.
- Slash-command driven workflow for switching models, saving sessions, compacting context, and browsing loaded skills.
- Session persistence and interruption support for longer investigative workflows.

KittyChain also includes built-in onchain analysis tools for common investigation tasks:

- Address balance lookup
- Address identity and label lookup
- Address transfer inspection
- Malicious address screening
- Token info lookup
- Token security checks

This makes KittyChain a practical fit for wallet triage, token due diligence, suspicious-address checks, and general blockchain research directly from the terminal.

## Usage

Run the interactive terminal UI:

```bash
kittychain
```

Run the coding-focused mode:

```bash
kittychain --code
```

Run a one-shot prompt and exit:

```bash
kittychain -p "Check this wallet and summarize the risk signals"
```

Resume a saved session:

```bash
kittychain -r session_1234567890
```

Open the configuration wizard:

```bash
kittychain --config
```

You can also start KittyChain with the module entry point:

```bash
python -m kittychain
```

When the CLI is busy, press `Esc` to interrupt the current run at the next safe checkpoint.

## Startup Modes

- `kittychain` or `kittychain --chain`: load the default on-chain investigation toolset.
- `kittychain --code`: load the coding-focused toolset for software engineering tasks.

## Interactive Commands

Inside the REPL, KittyChain supports:

- `/help`
- `/reset`
- `/skills`
- `/<skill name>`
- `/model <name>`
- `/tokens`
- `/compact`
- `/save`
- `/sessions`
- `/quit`

The `/skills` command shows the skills loaded at startup. Slash commands also support prefix matching while typing, making it easier to discover available commands and skills from the terminal.
