Practices

Claude Code keeps a transcript of every session on your machine. selan-practices reads the transcripts of the repository you are in and counts what those sessions did: what every request carried, which commands ran and how often, which skills were used, and which checks ran before a commit.

From those counts it proposes changes to how the repository is set up for Claude Code. Each proposal quotes the line it came from and the saving over the period the transcripts cover. Something the sessions did once is not a proposal.

On a new repository with no sessions yet, it starts from the files instead: see Start here.

If you have never set Claude Code up for a repository, the glossary at the end explains the five files and settings it talks about.

On the Selan CLI it is already installed. Selan's plugin catalog adds it by default, so there is nothing to do.

Anywhere else, run these two lines inside Claude Code:

/plugin marketplace add selan-ai/selan-practices
/plugin install selan-practices@selan-practices

It needs python3 on your PATH, and nothing else. The source is public and MIT licensed at github.com/selan-ai/selan-practices.

Start Claude Code inside the repository you want to look at. Each command reads the sessions of the directory it runs in, and no other.

/selan-practices:setup

Run this first. It works on a new repository with no history, from the files alone.

What it shows. What the repository has, in five lines at most: the stack, the checks it has, whether a red pipeline blocks a merge, its CLAUDE.md, and how many sessions there are to learn from.

What it proposes. A plan of at most five items. Each one says in a plain sentence what the thing is and why it helps, before any file name. It skips what is already in place. The items come from one list, in this order: a CLAUDE.md, turning on merge enforcement, moving a check that runs only after merge onto merge requests, code review, and dead-code detection as a suggestion. Where a component does the item, the plan names it.

You pick, it writes. Answer with the numbers you want, or “all”. It makes those changes, runs each one's check and shows you the diff. It never commits.

With fewer than five sessions, it ends by saying to run it again in two weeks. By then the sessions can show what to cut and what is missing.

/selan-practices:install code-review
/selan-practices:install dead-code

Each component adds one practice to the repository. With no name, the command lists the two and says which is already installed.

It reads the repository's CLAUDE.md and CI file first, and follows their conventions, such as runner tags and the package manager. It says in three lines what it will add, adds it, runs the component's own verification and shows you the diff. It never commits.

The next three commands are audits. They read what the repository's sessions did, so they need a few weeks of them. Then they show what to cut and what is missing.

/selan-practices:context-audit

What it looks at. CLAUDE.md is sent with every request, so its size times your request count is often the largest single cost. The audit also counts command output that was filtered after the fact, work done in another repository from this one, large and generated files read, and paths CLAUDE.md names that no longer exist.

A real finding. One repository had a 444-line CLAUDE.md, sent with every request. In another, sessions ran npx tsc | grep -v node_modules 1,988 times: the whole type check output, cut down after it had already been produced.

What it proposes. A CLAUDE.md under 200 lines, with the costly sections that only one kind of task needs moved into a rule file or a skill. For the filtered command, one quiet script that prints only what the filter kept, named in CLAUDE.md in place of the command.

/selan-practices:skill-audit

What it looks at. Every skill and agent a session had: the repository's own, your personal ones and the ones plugins bring. Then which ran, which failed, and which were worked around, where a session ran a skill's own commands by hand instead of calling it. It also flags two skills with the same name, and throwaway scripts written to /tmp in session after session.

A real finding. A project skill had the same name as a skill in the developer's own ~/.claude. Only one of the two ever ran, and it was not the project's, so sessions kept writing their own watch scripts in /tmp instead of using the one the project skill already had.

What it proposes. Rename or merge one of the two, keeping the one that holds the scripts the sessions needed. It never deletes a personal or plugin skill itself: it tells you what to remove.

/selan-practices:quality-gates

What it looks at. The repository's checks, cheapest first: format, lint, typecheck, build, unit, integration, e2e, budget, secrets, review. For each one it shows where it runs: a local command someone has to remember, a hook, a CI job that only advises, or a CI job that blocks the merge. From the transcripts it counts commits made with no check since the last edit, and the CI failures sessions ran into.

A real finding. A site whose only check ran after merge, on the default branch, so a broken change was already merged when it failed. And nine repositories where a red pipeline did not block the merge at all, because the project setting that requires a green pipeline was off.

What it proposes. A blocking job on merge requests for a check that only ran after merge. For the merge setting, which is not a file, it names the setting to turn on: “Pipelines must succeed” on GitLab, required status checks on GitHub. Where commits often go in unchecked, a hook that runs the quick check before git commit.

setup and the three audits each work in three steps, over two turns.

1. It proposes. The first turn lists the changes. Each one says what to change, quotes the line from the report it comes from, and names the file it touches. An audit also gives the numbers, and puts the largest saving first. It ends with one question: which ones to apply.
2. You pick. Answer with the numbers you want, or none.
3. It writes. The second turn makes only those changes and shows you the diff. It never commits. Review the diff and commit it yourself.

If a repository has no sessions yet, an audit says so and stops. There is nothing to count, and a setup written without evidence tends to cost more than it saves. Start here works from the files instead.