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. When you do not yet have enough language or background to form a question, it first offers one concrete foothold and lets your response set the direction. When several explanations are in play, Idea Lab helps draw, attack, compare, and check them without forcing an early winner. Both ship as skills for any AI tool that reads SKILL.md files — Claude Code, Codex, and the like.

Installing

Most people get exloop by installing newlife, which depends on it:

python -m pip install newlife
newlife start my-research

start installs the exloop and Idea Lab skills, together with newlife's own, into every AI tool found on the machine.

On its own:

python -m pip install exloop
python -c "import exloop; print(exloop.skills_dir())"

and copy the skill directories it contains 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.

Idea Lab is not a second entry point that must be completed first. It is an optional reasoning pattern inside exploration. The AI uses it when competing or underspecified explanations need to be made explicit, challenged, and distinguished.

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), the state model, and a bounded evidence-review method that returns source checks to the current exploration.
• skills/idea-lab/SKILL.md with domain profiles for formal theory, empirical and causal research, simulation, engineering and product mechanisms, and interpretive research.
• 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.

This repository

python3 skills/exloop/scripts/exploration_state.py self-test
uv build --out-dir dist && python3 scripts/check_release_artifacts.py dist

The skill is used downstream by newlife, which depends on this package. Apache-2.0.