Metadata-Version: 2.4
Name: skillrunes
Version: 0.1.1
Summary: Analyze coding-agent session transcripts and recursively improve a SKILL.md file
License: MIT
Keywords: agents,ai,cli,observability,skills
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.28
Requires-Dist: fastapi>=0.111
Requires-Dist: jinja2>=3.1
Requires-Dist: pydantic>=2.7
Requires-Dist: python-dotenv>=1.0
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn[standard]>=0.30
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# SkillRunes

Analyse coding-agent session transcripts and recursively improve a `SKILL.md` file.

SkillRunes turns past coding-agent sessions into reusable project memory. It
reads local transcript files, extracts what the assistant tried, what worked,
what failed, and what patterns are worth remembering, then uses those learnings
to generate or update a project `SKILL.md`.

The goal is simple: each time you run SkillRunes, your project-level assistant
instructions get a little sharper.

SkillRunes is provider-based. The first working provider is **Claude Code**.
Codex support is planned and exposed as an experimental provider path, but
transcript ingestion is not implemented yet.

## How It Works

1. SkillRunes scans transcript files for the current project.
2. New sessions are parsed and archived locally.
3. A model extracts structured session summaries.
4. SkillRunes synthesizes those summaries into a versioned `SKILL.md`.
5. The dashboard shows session metrics, failure patterns, and skill history.

All SkillRunes state is written inside the current project under `.skillrunes/`.

## Install

```bash
pip install skillrunes
```

## Usage

```bash
# Initialise for the current project
skillrunes init

# Analyse new sessions and update SKILL.md
skillrunes run

# Choose a transcript provider explicitly
skillrunes run --provider claude_code

# Preview changes without writing files
skillrunes run --dry-run

# Launch the local observability dashboard
skillrunes visualize
```

## Setup

SkillRunes needs model access when running transcript analysis.

You can use an Anthropic API key:

```bash
cp .env.example .env
# Edit .env and set ANTHROPIC_API_KEY=sk-ant-...
```

Or, if no `ANTHROPIC_API_KEY` is set, SkillRunes falls back to the local Claude
Code CLI:

```bash
claude --print
```

That means SkillRunes can run without an Anthropic API key as long as Claude
Code is installed and authenticated. Without either an API key or a working
Claude Code login, `skillrunes run` cannot extract summaries.

Provider selection can also be configured with:

```bash
export SKILLRUNES_PROVIDER=claude_code
```

## Providers

Supported provider names today:

- `claude_code` — supported, default
- `codex` — planned / experimental; currently raises a clear not-implemented error

The Claude Code provider reads JSONL transcripts from `~/.claude/projects/` and
matches sessions to the current working directory.

## Local Files

Running SkillRunes creates:

- `.skillrunes/sessions/` — raw transcript archives and extracted summaries
- `.skillrunes/skills/` — versioned `SKILL.md` history
- `.skillrunes/metrics.json` — dashboard metrics
- `SKILL.md` — the current generated skill file

## Roadmap

- Claude Code provider
- Codex provider
- Cursor provider
- Provider-agnostic dashboard
