Alku

Alku is a meta-framework for modern autonomous agentic development.

Right now it supports only Codex and Claude.

Features

Alku bundles and installs several 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 takes completely ownership on the root docs directory and uses it for project documentation.

Install

To install use these commands:

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:

cd /path/to/repository
alku init
alku docs check

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.

Preview initialization without writing anything:

alku init --dry-run --json

Installed workflows

Alku installs five user-facing skills:

• alku-workflow — deliver one bounded feature from plan through validation.
• alku-auto — work through eligible planned features sequentially.
• alku-brainstorm — inspect the project and propose prioritized future work.
• alku-docs — audit and reconcile repository documentation.
• alku-architecture — audit high-level structure and architectural drift.

What Alku manages

Alku owns the repository's root docs/ tree. It organizes product intent, implemented features, and candidate proposals into a validated closed schema that agents can query and maintain predictably.

Alku also manages explicit portions of AGENTS.md, the CLAUDE.md import, bundled provider skills, and named agent profiles. Authored content outside those boundaries is preserved. Unknown, malformed, or unmarked collisions fail closed instead of being overwritten.

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 .