Metadata-Version: 2.4
Name: jun
Version: 0.1.1
Summary: Raise a daemon that hunts while your AI coding agent works.
License-Expression: Apache-2.0
License-File: LICENSE
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.

## 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 off        # remove the Claude Code hooks
jun wrapped    # print the shareable daemon card
jun new        # release your daemon and start fresh
```

**The first time you run `jun`, it offers to connect to Claude Code for you** —
say yes and you're set (or run `jun init` yourself). After that, a hunt starts
*on its own* the moment your agent picks up a task, your daemon only grows from
that real work, and jun flags it the instant Claude needs your input.

## 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 three hooks to `~/.claude/settings.json`:
`PostToolUse` (each tool call → a catch), `Stop` (ends the hunt), and
`Notification` (Claude needs you → a "⚠ Claude needs you" alert in jun, so you
never miss a permission prompt while you're watching the hunt).

The hook is written as an absolute `<python> -m jun ...` command, so it works
even when `jun` isn't on your `PATH`. **Restart Claude Code after `jun init`**
so it reloads the hooks. `jun off` removes them cleanly.

For the hooks to keep working, install jun persistently (`uv tool install jun`)
rather than via the ephemeral `uvx` — `jun init` records the path of the Python
that ran it, and an `uvx` environment is deleted after the run.

## Status

Working: the agent connection (Claude Code hooks → live hunts that start on
their own and grow the daemon, plus a "Claude needs you" alert), the daemon
(generative ASCII), the hunt with
**focus** (a hunt can collapse — every catch matters), combo surges,
**golden tokens** (a rare jackpot that can mutate the daemon with a **spark**),
a **daily streak** (with a one-miss shield), **evolutions** (three permanent
forks → eight daemons), daily objectives, training mode, the `jun wrapped`
card, crash-safe atomic saves, first-run intro and `?` help.

## Development

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

## License

jun is released under the Apache License 2.0 — see [LICENSE](LICENSE).
Release notes live in [CHANGELOG.md](CHANGELOG.md).
