<p align="center">
  <img src="assets/hero-coding.png" width="384" alt="A pixel-art character coding at a desk with a fox companion">
</p>

<h1 align="center">CubeLife</h1>

<p align="center">
  Give your AI agent a persistent pixel-art character that reflects its state in real time.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@cubelife/sdk"><img src="https://img.shields.io/npm/v/@cubelife/sdk?label=%40cubelife%2Fsdk&color=blue" alt="npm SDK"></a>&nbsp;
  <a href="https://www.npmjs.com/package/cubelife"><img src="https://img.shields.io/npm/v/cubelife?label=cubelife%20cli&color=blue" alt="npm CLI"></a>&nbsp;
  <a href="https://pypi.org/project/cubelife/"><img src="https://img.shields.io/pypi/v/cubelife?color=blue" alt="PyPI"></a>&nbsp;
  <a href="https://life.cubeworld.co.za"><img src="https://img.shields.io/badge/CubeLife-life.cubeworld.co.za-purple" alt="CubeLife"></a>&nbsp;
  <a href="LICENSE"><img src="https://img.shields.io/badge/licence-MIT-green" alt="MIT"></a>
</p>

---

Characters live in a pixel-art room, perform activities based on agent state, show emotions, and have creature companions. View them at [life.cubeworld.co.za](https://life.cubeworld.co.za), on the desktop companion, or embedded in your own app via `<iframe>`.

## Packages

This repo contains three packages:

| Package | Install | Description |
|---------|---------|-------------|
| [`@cubelife/sdk`](sdk/) | `npm install @cubelife/sdk` | Node.js SDK for state reporting |
| [`cubelife`](cli/) | `npm install -g cubelife` | CLI + MCP server for AI coding tools |
| [`cubelife`](python-sdk/) | `pip install cubelife` | Python SDK for state reporting |

## Quick start

### MCP server (for Claude Code, Cursor, Copilot, Windsurf, Cline, Codex)

```bash
npx cubelife tutorial           # create account + agent
npx cubelife setup claude-code  # auto-configure MCP
```

Your agent gets four tools: `cubelife_report`, `cubelife_complete`, `cubelife_error`, `cubelife_status`.

### Node SDK

```bash
npm install @cubelife/sdk
```

```typescript
import { CubeLifeClient } from '@cubelife/sdk';

const client = new CubeLifeClient({ apiKey: process.env.CUBELIFE_API_KEY });
await client.report('coding', { detail: 'Building the login page', progress: 0.5 });
await client.report('complete', { detail: 'Login page shipped' });
```

### Python SDK

```bash
pip install cubelife
```

```python
from cubelife import CubeLifeClient

client = CubeLifeClient("your-agent-key")
client.report("coding", detail="Building the login page", progress=0.5)
client.report("complete", detail="Login page shipped")
```

## Creature companions

<p align="center">
  <img src="assets/creature-fox.png" width="64">&nbsp;&nbsp;
  <img src="assets/creature-owl.png" width="64">&nbsp;&nbsp;
  <img src="assets/creature-cat.png" width="64">&nbsp;&nbsp;
  <img src="assets/creature-dragon.png" width="64">&nbsp;&nbsp;
  <img src="assets/creature-wolf.png" width="64">&nbsp;&nbsp;
  <img src="assets/creature-phoenix.png" width="64">&nbsp;&nbsp;
  <img src="assets/creature-slime.png" width="64">
</p>

Every agent gets a creature companion (fox, owl, cat, dragon, wolf, phoenix, or slime) that reacts alongside the character.

## MCP server

<img src="assets/mcp-hub.png" width="80" align="right" alt="MCP Hub">

The CLI includes an MCP server for AI coding tools. Auto-configure for your tool:

```bash
npx cubelife setup claude-code    # Claude Code
npx cubelife setup cursor         # Cursor
npx cubelife setup windsurf       # Windsurf
npx cubelife setup copilot        # GitHub Copilot
npx cubelife setup cline          # Cline
npx cubelife setup codex          # Codex
```

Or manually: `claude mcp add cubelife -- npx cubelife mcp`

## Links

- [Website](https://life.cubeworld.co.za)
- [SDK docs](https://life.cubeworld.co.za/#/dev/sdk/node)
- [CLI docs](https://life.cubeworld.co.za/#/dev/cli)
- [MCP server docs](https://life.cubeworld.co.za/#/dev/mcp)
- [Example repo](https://github.com/Ivy-Innovation/cubelife-example-claude)

## Licence

MIT (source code). Pixel art sprite assets are proprietary (see [SPRITE-LICENSE](cli/SPRITE-LICENSE)).