Metadata-Version: 2.5
Name: exloop
Version: 0.1.0
Summary: Human-led exploration with a persistent map: the exloop skill for any AI tool that reads SKILL.md, plus the zero-dependency state helper it uses.
Author: hzshen88
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: claude-code,codex,exploration,human-in-the-loop,research-questions,skill
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# exloop

**Human-led exploration with a persistent map.** An AI companion that does not answer
your question for you: it asks one or two honing questions, walks one edge at a time,
keeps a map of where you have been, and offers the next step that is within reach. It
ships as a skill for any AI tool that reads `SKILL.md` files — Claude Code, Codex, and
the like.

## Installing

Most people get exloop by installing [newlife](https://pypi.org/project/newlife/), which
depends on it:

```bash
python -m pip install newlife
newlife start my-research
```

`start` installs the exloop skill, together with newlife's own, into every AI tool found
on the machine.

On its own:

```bash
python -m pip install exloop
python -c "import exloop; print(exloop.skills_dir() / 'exloop')"
```

and copy the directory that prints into your AI tool's skills folder
(`~/.claude/skills/`, `~/.codex/skills/`, ...).

## Using it

Open a folder in your AI tool and say:

> Explore this with me: *your curiosity*

The AI asks; you answer and decide. The map is kept silently in
`~/.exloop/explorations/<slug>/`, one folder per exploration — the same folder whichever
AI tool you switch to, because the identity is the slug, not the chat session. When you
close an exploration the AI archives the record into your research repository
(`explorations/<slug>/`). When a boundary has become a decidable question — you can say
what measurement would make the answer different — the AI says so once, and on your yes
hands the record to newlife (`questions/<slug>/origin/`), where the preregistration
discipline takes over.

## What is in the package

- `skills/exloop/SKILL.md` with its references: the protocol (four events — started,
  marked, pivoted, closed — and the map as their projection) and the state model.
- `skills/exloop/scripts/exploration_state.py`: the zero-dependency helper the skill
  runs — `init`, `mark`, `pivot`, `show`, `close`, `list`, `archive`, `handoff`, and a
  `self-test`.
- `exloop.skills_dir()`: the one Python function, so that newlife can locate the skill
  files. exloop has no other API and no dependencies.

Requires Python 3.11 or newer.
