basicly logo

basicly

basicly writes the instruction files for Claude Code, Codex and Copilot from one catalog of rules. It adds git hooks that check every commit.

Use it when one or more coding agents work in your git repository. Every agent then follows the same rules and passes the same gates.

Install

Install into a git repository

Run this inside your git repository. On Linux, macOS or the Windows Subsystem for Linux (WSL):

$ curl -fsSL https://niksavis.github.io/basicly/install.sh | sh

On Windows (PowerShell):

> irm https://niksavis.github.io/basicly/install.ps1 | iex

You need git and uv. The script installs uv when it is missing, and uv gets Python 3.14 or later. You also need Node.js and the markdownlint-cli2 package in the repository, for the markdown gate. Without them, install stops before it writes a file. The script installs the latest release. To read the script before you run it, or to pick a version, see the install options.

What you get

Rules, gates, a tracker and a loop

Rules

The catalog is a set of YAML files that hold the rules for your agents. basicly writes them into the files each agent reads: CLAUDE.md, AGENTS.md, copilot-instructions.md, skills and subagents.

Gates

A gate is a check that refuses a commit when it fails. basicly runs the gates in git hooks and in agent hooks. Continuous integration (CI) runs them again.

A tracker

The tracker stores records of work, their dependencies and the result of each gate. It keeps them in a log in .basicly/ledger/, which you commit with your code.

A loop

The loop command takes one record from creation to a merged change. It builds each record in its own git worktree, a second working copy of the repository. Another agent can continue the work, because the loop reads the state from the tracker.

First use

Make the first commit

Open your coding agent in the repository. It now reads the rules in its instruction file. Each commit needs a Conventional Commits subject and the id of a tracker record that you claimed.

The tutorial shows both on a test repository that you can delete. It sends no request to a paid AI model. Unblock a commit explains each refusal and its fix.

Install adds no basicly command to your PATH. Add this function to your shell startup file, with the version you installed:

basicly() { uvx --python '>=3.14' --from https://github.com/niksavis/basicly/releases/download/v0.46.3/basicly-0.46.3-py3-none-any.whl basicly "$@"; }

Kits

Install one kit alone

A kit is a part of basicly that installs without the rest. There are four kits. Each has no dependencies and needs Python 3.9 or later.

$ uv tool install 'git+https://github.com/niksavis/basicly@v0.46.3#subdirectory=packages/basicly-tracker'
$ basicly-tracker init

The kits reference gives the commands of the tracker, comments and tier kits. The board README gives the board's commands.

Learn more

Documentation