The things around your code go stale as it changes — the docs, the design intent, the security findings, what the code is supposed to do — and nobody redoes that upkeep by hand, in the right order, every time. freya-devkit derives a dependency graph from your code, then gives each of those artifacts a skill that re-syncs what a change actually reached.
📖 New here? Read the explainer → alexsendula.github.io/freya-devkit — a no-install webapp: the problem, the one idea, how to install and use it, and what is not proven.
Ten skills, on any agent that loads the Agent Skills standard.
A change is known by the blast radius the graph reports rather than by the files you happened to
touch, and one skill, freya-wrap-up, runs the others in order and lands the result in two commits.
Claude Code and GitHub Copilot are both validated on a live run. Other hosts that load the standard should work, and have not been checked here. Whether the graph reads your language depends on which backend you pick:
| Backend | Reads | Needs |
|---|---|---|
homegrown |
TypeScript, JavaScript, Python, Go — 4 languages | nothing; ships with the toolkit |
graphify |
40 languages, and which symbol each edge leaves and arrives at | its binary on PATH |
homegrown is the floor and runs unless you say otherwise, so a locked-down machine where you
cannot install anything still gets a graph. freya install asks you once and records the answer in
the project, so a clone and CI resolve the same backend you do.
git clone https://github.com/AlexSendula/freya-devkit.git
cd freya-devkit
./install.sh # Windows: .\install.ps1The checkout is the store: each skill is symlinked into your agent's skills directory and the
freya launcher lands at ~/.local/bin/freya. Pick targets with --agent claude --agent copilot;
--copy where symlinks are awkward, --dry-run to preview, --uninstall to remove. Python 3.9
or newer is the only requirement — every script here is stdlib-only.
One manual step: ~/.local/bin has to be on your PATH. The installer never edits your shell
profile; it prints the line to add. Expect that note — a stock macOS never has that directory on
PATH. If freya doctor answers command not found, this is the step that was skipped.
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # or ~/.bashrcClaude Code can install from the plugin marketplace instead — /plugin marketplace add AlexSendula/freya-devkit, then /plugin install freya-devkit@freya-devkit. Skills appear as
/freya-devkit:freya-code-graph, and no PATH step is needed.
Use one path or the other. With both, Claude registers every skill twice.
freya doctorwarns when it sees this.
Windows, and keeping it current
On Windows, prefer install.ps1 on either path — only the installer writes the freya.cmd
shim Windows needs to run the launcher by name. Creating a symlink there needs Developer Mode or
an elevated shell, so the installer checks first and falls back to --copy on its own rather than
failing.
freya update fast-forwards the store and re-links it — a skill added upstream gets a link,
one removed loses its stale one. It refuses rather than guessing when something is off (no git, a
dirty tree, an unreachable remote), and --dry-run writes nothing. On the plugin path the
equivalent is /plugin marketplace update freya-devkit. Reload your session afterwards either
way: agents read their skill list once, when the session starts. Coming from 0.1.0, every skill was
renamed — the recipe is
migrations/skill-rename.md.
The full sequence and its exit codes are in DEPLOYMENT.md; symptom-by-symptom fixes are in TROUBLESHOOTING.md.
cd path/to/your/project
freya doctor # is the install healthy, and is the launcher on PATH
freya init # or: freya init path/to/project
freya code-graph --build # the first graph; everything else reads itfreya init adds a short freya-devkit section to the project's AGENTS.md, fenced by comment
markers so re-running updates just that section and leaves the rest of your file alone.
Then ask your agent for a skill by name — "run the freya-docs-manager skill and update the docs".
One hyphen changes the meaning: freya <command> with a space is the CLI, freya-<skill> with
a hyphen is a skill name. On the Claude plugin path it is /freya-devkit:freya-docs-manager.
After you finish a change, ask for freya-wrap-up:
commit 1 ── your code
code-graph → docs-manager → spec-manager → behavior integrity + run → security scan
commit 2 ── everything those five regenerated
Two commits, so generated artifacts never land mixed in with your code. Skip phases with
--no-graph, --no-docs, --no-specs, --no-security.
freya-status is the read-only counterpart: what intent, tests, coverage and findings are
outstanding. It writes one file, knowledge-base/BACKLOG.md, and rewrites it completely each time —
so don't hand-edit that one.
One directory, knowledge-base/ at the project root — docs, specs, ADRs, declared intent,
security reports, the backlog and the behavior graph. It is meant to be committed, apart from a
small cache the toolkit regenerates;
ARCHITECTURE.md § Output Artifacts
marks every file tracked or ignored.
Two things land outside it: the AGENTS.md section, when you run freya init; and a .feature
scaffold in your code tree, written only when you accept a proposed behavior.
The security pass freya-wrap-up runs is the free one — its update mode is incremental and
stays in your session. The deeper scan and audit modes drive a real agent CLI as a pool of
headless workers and cost money: tens of dollars on a large repository. Neither runs without
asking. freya security audit --dry-run prints the plan and the ceiling and spends nothing.
| Skill | Keeps in sync | Reach for it when |
|---|---|---|
freya-code-graph |
the dependency graph | you need a blast radius — everything below reads this |
freya-docs-manager |
project documentation | code moved and the docs still describe where it was |
freya-spec-manager |
specs, ADRs, design decisions | a decision needs recording so it is not "fixed" later |
freya-behavior-graph |
what the code is supposed to do | you want the behaviors a change touches, or the code behind one |
freya-behavior-runner |
which tests actually cover which code | those behaviors need running to prove they still hold |
freya-codebase-security-scan |
security findings | after a change (free), or before a release (the paid modes) |
freya-codebase-security-resolver |
the same findings, interactively | you are working through what the scan found |
freya-dependency-vulnerability-check |
dependency CVEs | you want the supply chain checked rather than your own code |
freya-wrap-up |
all of the above, in order | you finished a change — this is the one to remember |
freya-status |
knowledge-base/BACKLOG.md |
you want to know what is outstanding before starting |
Most days that is two names — freya-wrap-up and freya-status. The rest are what wrap-up calls,
worth invoking directly when you want one artifact rather than the whole pass. They degrade rather
than fail: without a graph they fall back to a plain git diff, and the security scan reads your
specs and marks what it matches there as intentional design rather than reporting it. Per-skill
command tables: SKILL_REFERENCE.md.
Coherence, not enforcement. The patterns are guidelines, skills adapt them, and inferred specs carry a 0–100 certainty score rather than rounding to confident. The exception is the behavior layer, where a broken test link or a failing accepted behavior blocks until you deal with it.
Some of it has never been proven, listed as risk rather than reassurance. No agent CLI has ever
run on Windows: CI installs and tests the toolkit there, but no agent runs on that runner. Each
install mode is exercised on one platform only — symlink on Linux, --copy on Windows — which
leaves the opposite diagonal untested on both. And whether GitHub Copilot delegates at scale on a
large codebase has never been tried. Those are three of them; the live list is
roadmap.md.
The explainer site is the human-facing narrative,
organised by what you want rather than by feature (source in
knowledge-base/explanations/):
| Page | For |
|---|---|
| Home | The problem, the one idea, and what is not proven |
| Using it | Install, first run, the ten skills, what it writes and where |
| How it works | Architecture, how the graph is built, and how the pieces connect |
| Extending it | Writing a skill, the launcher, testing and CI |
| Reference | Where every command and artifact is documented |
| Decisions | The thirty-one ADRs, and what each one rejected |
| How it evolved | The plans that turned out wrong, and what replaced them |
The markdown under knowledge-base/ is the agent-facing source of truth, and the
site links to it rather than restating it:
philosophy.mdandpatterns.md— why these skills exist, and what they sharereference/— architecture, deployment, environment, security, testing, style, troubleshooting, developer guidedecisions/— the ADRs as markdown, each with its rejected alternativesroadmap.md— the single live backlogmigrations/— one-time moves between versions
That layout is what freya-devkit creates in any project it runs against, and this repo uses it on itself. Working on the toolkit itself: CONTRIBUTING.md. Release history: CHANGELOG.md.
MIT — see LICENSE.