Metadata-Version: 2.4
Name: jun
Version: 0.2.0
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

<div align="center">
  <img src="jun-logo.png" alt="jun" width="220">
  <h1>jun</h1>
  <p><em>the AI writes the code. you raise the daemon.</em></p>
  <p>
    <a href="https://pypi.org/project/jun/"><img alt="pypi" src="https://img.shields.io/pypi/v/jun?color=f2705a&label=pypi&style=flat-square"></a>
    <a href="https://pypi.org/project/jun/"><img alt="python" src="https://img.shields.io/pypi/pyversions/jun?color=f2705a&style=flat-square"></a>
    <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-Apache--2.0-f2705a?style=flat-square"></a>
  </p>
</div>

---

**jun is a tiny terminal game for the age of AI coding.** It runs in its own
pane beside Claude Code. Every tool call your agent makes becomes prey — catch
it in rhythm, chain combos, and raise a daemon that's a portrait of how you
actually code.

```sh
pip install jun
jun init    # connect Claude Code, then restart it
jun         # the hunt begins
```

> daemon getting too powerful? &nbsp;`jun off`.

---

## Claude Code works. you hunt.

The instant your agent picks up a task, the hunt is live. Its tool calls fly
in as tokens — catch them in the green, chain a combo, trigger a surge.
Every catch feeds the daemon you're raising.

| call            | becomes                                |
|-----------------|----------------------------------------|
| `edit`          | a strike                               |
| `bash`          | a heavy hit — land it in two           |
| `read` / `grep` | a wide, gentle scan                    |
| a quiet agent   | your daemon catches its breath         |

The daemon's **form is generative**, shaped by how you actually code. Lots
of edits grow more limbs. Lots of test runs grow armor. Lots of reading
grows more eyes. No two daemons are alike, and yours is the thing you
screenshot and share.

```
      ·˘˘˘·
   ╭─────────╮
   │ ● ● ● ● │
   │   ‿ ‿   │
   ╰─────────╯
    │ │ │ │ │
    ╨ ╨ ╨ ╨ ╨
```

---

## what works

- **Live hunts** that start on their own — driven by your agent's real tool
  calls, not a simulation.
- **Per-kind cursor motion** — a read drifts, a test run races, a thinking
  pause makes the cursor waver. The kind tells you how to time the catch.
- **Heavy tokens** — a test run takes two timed hits, one per cursor pass.
- **Golden tokens** — a rare jackpot, claimed with a quick double-tap in the
  zone. A perfect golden catch can permanently mutate the daemon with a
  **spark**.
- **Focus** as the stakes — misses drain it, a quiet agent lets it recover,
  and at zero the hunt collapses.
- **Combo surges** every five clean catches.
- **Evolutions** — four permanent forks, sixteen possible daemons.
- **Daily streaks** with a one-miss shield, and **daily objectives** that
  re-seed at midnight.
- **Training mode** — practice against a simulated agent. Banks nothing;
  the daemon records only real work.
- **`jun card`** — a shareable daemon card with your best run.
- **`?` help**, first-run intro, crash-safe atomic saves.

---

## 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 on its own when your agent works — that is the game,
and it is what grows your daemon. With no agent, `space` starts a training
run. The daemon is a record of your *real* coding.

---

## how it connects to Claude Code

jun is **standalone** — 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 becomes a hunt event
- `Stop` — ends the hunt
- `Notification` — surfaces "⚠ Claude needs you" in jun, so you never
  miss a permission prompt while you're catching tokens

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

If you installed jun with `uvx` (ephemeral), `jun init` would record a
path that disappears after the run — install jun persistently instead
(`pip install jun`, or `uv tool install jun`).

---

## all commands

```sh
jun            # play (the default)
jun init       # connect Claude Code's hooks (run once, then restart Claude Code)
jun off        # remove the hooks
jun card       # print the shareable daemon card
jun new        # release your daemon and start fresh
```

---

## development

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

Issues and PRs welcome — bug reports especially. Release notes live in
[CHANGELOG.md](CHANGELOG.md).

---

## jun is not productivity software

It is not a SaaS. It will not 10× your output. It's a daemon. It lives in
your terminal. It's a little bit feral — and that's the whole point.

> the AI doesn't need you. your daemon does.

Never be bored vibe coding again.

---

<sub>Released under the <a href="LICENSE">Apache License 2.0</a>.</sub>
