Metadata-Version: 2.4
Name: jun
Version: 0.1.0
Summary: A turn-based roguelike you play while your AI coding agent works.
License: MIT
Requires-Python: >=3.10
Requires-Dist: rich>=13.7
Requires-Dist: textual>=0.80
Description-Content-Type: text/markdown

# jun

Raise a **daemon** that hunts while your AI coding agent works.

jun runs in a terminal pane next to Claude Code. You hatch a daemon — a
creature that lives in your repo. When your agent works, your daemon **hunts**:
every tool call the agent makes flies in as a token, and you catch it in rhythm.
Catches chain into a combo; the daemon feeds on the essence and **grows**.

Its *form is generative* — shaped by how you actually code. Lots of edits →
more limbs. Lots of test runs → armor. Lots of reading → more eyes. No two
daemons are alike, and yours is the thing you screenshot and share.

While you're away, other developers' daemons wander through your den and leave
gifts, and a daily expedition ranks the whole community. You're never alone in
the terminal.

## Quick start

```sh
uvx jun                 # play (zero install)
uv tool install jun     # or install it permanently
```

```sh
jun            # play
jun init       # install Claude Code hooks (so the agent drives your hunts)
jun wrapped    # print the shareable daemon card
jun new        # release your daemon and start fresh
```

**Run `jun init` once** — that's what connects jun to your agent. After that,
a hunt starts *on its own* the moment your agent picks up a task, and your
daemon only grows from that real work.

## Controls

| key     | action                                            |
|---------|----------------------------------------------------|
| `space` | catch a token · start a training run               |
| `1` `2` | choose a form at an evolution fork                 |
| `esc`   | end the hunt · leave a screen                      |
| `?`     | help — the loop and the controls                  |
| `q`     | quit (always saved)                                |

A **live hunt** starts by itself when your agent works — that is the game, and
it is what grows your daemon. With no agent running, `space` starts a
**training** run against a simulated one: good for learning the catch, but it
banks nothing. The daemon is a record of your *real* coding.

## How it connects to Claude Code

jun is a **standalone program** — it never launches or wraps Claude Code. Run
it in a separate pane. `jun init` adds two hooks to `~/.claude/settings.json`:
`PostToolUse` (each tool call → a catch) and `Stop` (ends the hunt).

## Status

Working: the agent connection (Claude Code hooks → live hunts that start on
their own and grow the daemon), the daemon (generative ASCII), the hunt with
**focus** (a hunt can collapse — every catch matters), combo surges,
**evolutions** (three permanent forks → eight daemons), daily objectives,
training mode, the shared world (visitors, gifts, daily expedition), the `jun
wrapped` card, crash-safe atomic saves, first-run intro and `?` help.

Simulated for now: the shared world is generated on-device — genuinely
multiplayer needs a small registry server (the one swap left to make).

## Development

```sh
uv sync
uv run jun
```
