Alku

Alku prepares a repository for repeatable, documentation-led development by autonomous coding agents. It installs project-local workflows for Codex and Claude, maintains a structured documentation tree, and validates the state those workflows rely on.

Right now it supports only Codex and Claude.

Features

Alku bundles and installs five public skills:

1. alku-workflow — main entrypoint; responsible for a complete plan-to-implementation workflow for a single feature. Automatically added to AGENTS.md.
2. alku-auto — autonomous long-term development; takes all planned features and sequentially launches alku-workflow subagents for each one.
3. alku-brainstorm — check current project features and create plans for future project growth; launch when you have no idea what to do with the project.
4. alku-docs — generate, check, and reconcile documentation with code; should be run periodically (every 3 features as a baseline) to avoid mess and drift in documentation.
5. alku-architecture — check high-level project structure; should be run periodically (every 3 features as a baseline) to avoid project structure from becoming a mess.

Alku validates the root docs/ directory as a closed, structured collection. It preserves recognized authored records, owns generated indexes and explicitly marked projections, and reports collisions instead of adopting unmarked files. Move pre-existing documentation into the supported structure before relying on alku docs check.

Requirements and install

Alku requires Python 3.11 or newer. The recommended installation path uses uv, but uv is not a runtime dependency. Install Alku as a user-level tool:

uv tool install alku
uv tool update-shell
alku --version

Restart the shell if uv tool update-shell changes PATH.

Quick start

Run Alku from the repository you want it to manage. Preview initialization first if the repository already contains documentation or agent instructions:

cd /path/to/repository
alku init --dry-run
alku init
alku docs check --json

Initialization creates the documentation scaffold, updates the managed AGENTS.md workflow gate, makes CLAUDE.md import that shared policy, and installs the bundled skills and provider-native agent profiles. Restart active Codex or Claude sessions afterward so they discover the new files.

Initialization also appends a concise Managed by Alku section to the project README when that heading is absent. After reviewing the created files and restarting your agent session, start with one of these prompts:

Use the alku-workflow skill to implement <one bounded feature>.
Use the alku-brainstorm skill to propose the next useful project features.
Use the alku-auto skill to implement all eligible planned features.
Use the alku-docs skill to audit and reconcile the repository documentation.
Use the alku-architecture skill to audit the high-level project structure.

alku-workflow is the normal entrypoint for one feature. Use alku-auto only after reviewing the planned feature backlog because it delegates every eligible plan sequentially.

Command guide

alku docs generate can update managed files outside docs/, including AGENTS.md, a missing CLAUDE.md, and public or private skill files under .agents/skills/ and .claude/skills/. It refuses to repair a stale or malformed existing CLAUDE.md; rerun alku init for that recovery path. It does not install provider-native agent profiles. Review the complete repository diff afterward. A zero-diagnostic docs check or docs generate is silent in human mode even when generation wrote files; warnings are printed but still exit successfully. Use --json when an explicit result is useful.

Routine maintenance

alku docs generate
alku docs check
alku self check
alku self update

• docs generate refreshes generated indexes and stale Alku-owned projections.
• docs check performs read-only validation.
• self check reports whether PyPI has a newer release.
• self update explicitly installs a newer release and verifies the command.

Run alku --help or alku COMMAND --help for the complete command surface.

Development from source

uv sync --locked
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run ty check --extra-search-path src .
uv build

Install the current checkout for local testing with:

uv tool install --force .