sk8r

Keep your momentum. sk8r sets a project up so it actually runs: it works out what the project is, installs its dependencies, fills in local settings, adds run buttons to your editor, and checks that the app really starts — after one approval. Then it keeps a short, always-current briefing so the next AI session picks up where the last one stopped.

Pronounced skat-r. Python 3.11+, standard library only at runtime. Linux, macOS and Windows.

Quick start · Features · How it works · Commands · Results · Reference · Contributing

Contents

• Why
• Quick start
• Features
  • Ready
  • Upcoming
• How it works
• Safety
• Commands
• Configuration files
• Platforms
• Status
• Contributing
• License

Why

Cloning a project is easy. Getting it to run is where momentum dies: which Python, which package manager, which virtual environment, the .env nobody committed, the database URL, the command that starts the server, and whether it really started. AI coding assistants make this worse and better at once: they can do all of it, but they guess, and "it should work now" is not the same as a server answering.

Momentum also dies between sessions. A new AI session starts cold: it doesn't know what is done, what is next or which rules the project follows, so it re-reads everything or, worse, guesses.

sk8r turns both into predictable steps an assistant (or you) can run, preview and undo:

You:    Set this project up with sk8r; follow `sk8r guide`.
Agent:  Here is the plan:
        1. Write sk8r.toml (preset django, python=uv inferred from uv.lock)
        2. Write 3 run buttons into T3 Code (backup first)
        3. Setup: uv sync
        4. Add app settings to .env: SECRET_KEY, ALLOWED_HOSTS, DATABASE_URL, DEBUG (names only)
        5. Start check: wait for http://127.0.0.1:8000/admin/login/, then stop
        Approve?
You:    approve it
Agent:  configured ✓  dependencies installed ✓  dry-run verified ✓  launched ✓ (HTTP 200)

That exchange is a real run on a real Django project, from approval to a verified HTTP 200 in about 11 seconds. See results for it and for the less flattering runs that shaped sk8r.

Quick start

uv tool install sk8r                                      # from PyPI
uv tool update-shell                                      # puts sk8r on PATH if it isn't yet
sk8r --version

With an AI assistant in T3 Code: open your project and say "Set this project up with sk8r; follow sk8r guide." Review the plan, approve once, and the new run buttons appear in T3 (press Ctrl+R if they don't).

On your own, in a terminal:

cd your-project
sk8r run --dry-run      # see the whole plan; nothing is written or run
sk8r run                # do it, after one yes
sk8r start dev          # launch the profile's processes, one terminal tab each
sk8r undo               # changed your mind? reverse everything sk8r did here

Keep AI sessions in context:

sk8r pack init --dry-run --hook --remind claude   # preview adopting the briefing workflow
sk8r pack init --yes --hook --remind claude       # adopt it: pack, task list, AGENTS.md pointer, hook
sk8r status                                       # progress, next tasks, warnings

Features

Ready features ship in the current version and are covered by the test suite. Upcoming features are planned on the roadmap; their shape may change before they ship.

Ready

1. One-approval project setup — sk8r run

• One plan, one yes. Identification, configuration, run buttons, dependency setup, app settings and start checks are shown as a single numbered plan and carried out after one approval.
• Preview everything first. sk8r run --dry-run writes and runs nothing; --json returns one result object for an AI assistant.
• Leave parts out. --no-setup, --no-env and --no-verify drop steps from the plan; --pack adds context-pack adoption to it.
• Four honest states, reported separately because they are different claims: configured (sk8r.toml written), dependencies installed (setup recorded), dry-run verified (programs and paths exist) and launched (the app actually answered).
• Never rewrites your configuration. An existing sk8r.toml with profiles is left as it is.

2. Stack detection and presets — sk8r presets, sk8r init

• Six presets: django, django-vite, django-expo, fastapi-vite, node-next and python-server (catalogue).
• Choices inferred from your files, with the source shown in the preview: uv.lock → uv, poetry.lock → Poetry, requirements.txt → a project .venv, pyproject.toml alone → uv; pnpm-lock.yaml, yarn.lock or package-lock.json pick the Node tool.
• Safe automatic choice. Only a single full preset match is picked automatically; half matches ask you to choose with --preset.
• Python options: uv, poetry, venv (creates .venv and installs requirements; commands use the venv's Python directly, no activation) and plain. Node options: pnpm, npm, yarn.
• Parameters with validation (--set port=8001, --set backend_dir=api): paths, ports, text and choices are checked before anything is written.
• Presets are data, not code. sk8r init --preset <name> copies the profiles into sk8r.toml, appending after a comment that records your options, keeping your newline style and encoding, and writing atomically. Name clashes stop with a list; --rename old=new resolves them.
• Browse and inspect: sk8r presets list, presets show <name> (the exact TOML) and presets detect (read-only).
• Repair a generated profile: sk8r init --replace <profile> --dry-run shows a diff and replaces only a profile that init generated and nobody edited.

3. Launching — sk8r start

• One terminal tab per process: Windows Terminal (a PowerShell 7 tab each), a detached tmux session on Linux (and on macOS with tmux), or Terminal.app windows on macOS.
• Fallback that still helps: when no terminal is available, sk8r prints the exact commands.
• Profiles and variants, for example sk8r start dev lan or sk8r start dev phone.
• Exact plans: --dry-run prints every tab, folder and command; --tab <t> --here runs one tab in the current terminal (what each editor button runs).
• Checked before launch. The profile's readiness checks run first; nothing starts while one blocks (--no-check skips them). Tabs whose setup is incomplete are refused.
• Shell shortcut: sk8r shortcut powershell|bash|zsh prints an opt-in start function; nothing edits your shell profile.

4. Dependency setup — sk8r setup

• Declared, shown, confirmed. Each profile's setup (uv sync, poetry install, pnpm install, venv creation…) is printed with its folder and runs only after a yes.
• Recorded completion. Successful setup is recorded with the hashes of its inputs (lock or requirements files), so an empty or outdated .venv never counts as ready.
• Independent entries. A failed pnpm install doesn't stop the Python environment.
• Plain warnings. Choosing plain beside a requirements file warns that dependencies are unmanaged.

5. App settings — .env defaults

• Fills only what is missing. Required keys come from .env.example and the preset; a key is added only when it is missing or empty.
• Local-development defaults for Django: a SQLite DATABASE_URL, a generated SECRET_KEY, DEBUG=True and ALLOWED_HOSTS=localhost,127.0.0.1. Add your own with sk8r defaults.
• Names only. Values are never printed, logged or stored by sk8r, and values you set are never changed.
• Gated start. Until required keys are filled, doctor reports env-missing and start waits.

6. Start check — sk8r verify

• A real HTTP answer, not a guess: sk8r starts the tab in the background, waits for any HTTP response at its check_url (Django: /admin/login/, Vite: port 5173), then stops it.
• Cleans up after itself. It stops only its own process tree and confirms the port is free again.
• Refuses busy ports and never touches processes it didn't start.
• Useful failures. When the app doesn't answer, the last log lines are shown and kept under .git/sk8r/verify/.
• A "check" button per tab in T3 Code.

7. Editor run buttons — T3 Code

• Buttons written for you. One button per tab and one per setup, written straight into T3's project settings (with a timestamped backup first) and/or a shared t3.json (--t3 file|settings|both|off).
• Only sk8r's entries. Existing scripts are kept; only entries whose id starts with sk8r- are replaced.
• Project defaults for T3: the model and thread mode (local or worktree) you prefer, applied to every project you set up; different existing values are kept unless you override them.
• Import path for any setup without direct settings access: import t3.json in T3's project settings.

8. Readiness check — sk8r doctor

• Read-only. Changes nothing and runs no project commands.
• Checks in order: Python, sk8r on PATH, Git; the repository, sk8r.toml, records branch, plan and pack; the terminal launcher; each profile's folders, required paths, programs, setup and app settings; t3.json freshness.
• Every finding has a fix, a stable code (program-missing, setup-needed, env-missing…) and a level (ok, warn, block). --json gives one machine-readable object.

9. Undo — sk8r undo

• Everything journalled. sk8r.toml, t3.json, T3 buttons and project defaults, setup records, created files and folders, .env additions, and context-pack adoption (pack, task list, AGENTS.md block, hook and reminder).
• Reversible in one command. sk8r undo --dry-run lists changes newest first; --yes reverses them byte for byte, restoring editor buttons sk8r replaced.
• Your edits win. Anything changed since sk8r wrote it is reported and left alone.

10. Your defaults — sk8r defaults

• One file for your preferences: preferred tools and ports, terminal launcher, start-check timeout, where buttons go, T3 model and thread mode, and extra .env defaults.
• Edit safely: defaults init, defaults set run.launcher tmux and defaults unset … edit one setting atomically, keeping comments and line endings.
• Clear precedence, shown with each value's source: what you type wins over the project's files, your defaults and preset defaults.

11. AI assistant guide — sk8r guide

• Versioned instructions an assistant follows to set a project up in T3 Code, centred on sk8r run's one-approval plan; --json gives the same as data.
• No model inside. sk8r itself never calls a model; the assistant runs sk8r's commands and you approve.

12. Context pack for AI sessions — sk8r pack, sk8r pack init

• A short briefing (docs/context-pack.md) a new AI session reads first: agent rules, the next task, open questions, and a generated block of current facts, kept under 10 KB by trimming rules.
• One-command adoption: sk8r pack init creates the pack from a template, finds your task list (TODO.md or todo.md, exact spelling kept) or creates a starter one, sets the plan, pack and records branch in sk8r.toml, adds a marked start-here block to AGENTS.md, and fills the block — as one numbered plan in plain words, after one yes, and fully undoable.
• Safe refresh. sk8r pack rewrites only the generated block between its markers, on the records branch only, and changes no other byte; --check exits 3 when the pack is stale.
• Stable by design. The block changes only when the plan's facts change, so a committed pack stays current (an optional recent-commits list is off by default).

13. Project status — sk8r status

• The facts in one place: current branch or detached HEAD, uncommitted changes, progress per phase, the current phase, next tasks per teammate, branch locks and plan warnings.
• Read from the records branch without switching branches; --json gives one versioned object. It never writes.

14. Commit hook and agent reminders — --hook, sk8r hook, sk8r remind

• Optional pre-commit hook that refreshes and stages only the pack when you commit plan changes. It respects core.hooksPath, keeps an existing hook's lines (inserting its stanza before the final exit), and always exits 0, so it never blocks a commit.
• Installed only when asked (sk8r pack init --hook) or by hand from sk8r hook show.
• Claude Code reminder (--remind claude) merges a post-commit reminder into .claude/settings.json, keeping your other settings; it tells the model when the pack is stale and never refreshes anything itself.
• Portable routine for other assistants: sk8r pack --check after a commit (details).

15. Configuration check — sk8r config check

• Validates sk8r.toml (versioned schema, unknown keys rejected, repository-relative paths only) without running anything.

16. Repository trust — sk8r trust

• You approve a project's commands once. Before sk8r start (and the editor's run buttons), sk8r setup and sk8r verify run anything a project's sk8r.toml declares, sk8r shows every command with the full path of the program it runs, and asks.
• Any change asks again, with the added and removed lines, so a git pull can't slip in new commands.
• Approvals live on your machine, outside every repository, so a cloned or copied project never arrives pre-approved. sk8r trust --revoke removes one.
• One plan, still one yes. sk8r run lists the commands in its plan when they are new or changed; configuration sk8r writes itself is approved automatically.
• Programs are what they say. Bare names like git are found only on PATH, never in the project or current folder, and the start check only connects to this machine.

Upcoming

Planned, in roughly this order. None of these ship yet.

• More presets. More stacks, mostly from contributors; each is a small data file plus a test.
• Verification profiles and portable handoffs. Richer, declared checks beyond "the server answers", and handoffs that move between machines and assistants.
• Backup and move — the backup tool. Move a project between machines: Git history and uncommitted work, folders that live outside the repository, optional data, and project-filtered AI chat history, with an archive manifest, ownership filters, upload to a committed backend and restore validation.
• Agents kit. A reusable setup for teams of AI agents: a shared agreement, teammate permissions, task briefs, record and claim rules, and a helper for working one step at a time.
• Workflow playbook. A WORKFLOW.md written from the tested routines: approval, pauses, tests, commits, the pack, status and handoff.
• Docs export (optional). Export project records to Word and Excel.
• Browser kit. Isolated browser environments, sign-in, pinned time and screenshot helpers for checking web apps, while the core stays standard-library only.

How it works

1. Identify. sk8r matches the project against presets and infers the choices from the files that are there. It writes one small file, sk8r.toml.
2. Check. sk8r doctor explains what is missing and how to fix it, without changing anything.
3. Install. Declared setup runs only after your yes: create the venv, install requirements, pnpm install. Completion is recorded, so an empty or outdated .venv never counts as ready.
4. Configure. Missing local-development settings are added to .env. Values you set are never changed, and values are never printed.
5. Buttons. Run buttons go into your editor's project settings (T3 Code today) and a shared t3.json, with a backup first.
6. Verify. sk8r starts each server in the background, waits for a real HTTP answer, stops it, and confirms the port is free. It refuses ports already in use and never touches your servers.
7. Brief. Optionally, sk8r pack init adds a context pack that the next AI session reads first, kept current by sk8r pack and an optional commit hook.

Your preferences live in one file (sk8r defaults). A project's own files and anything you type always win.

Safety

• Nothing changes without a yes. Every write and install is shown first; without a terminal and without --yes, sk8r refuses.
• Everything can be undone. sk8r journals each change in the project and sk8r undo reverses it, restoring editor buttons it replaced; anything you changed since is left alone.
• Secrets stay secret. .env values are never printed, logged or stored by sk8r.
• Your processes are yours. sk8r never kills, reuses or frees a port it did not open.
• A project's commands run only after you approve them, once per version, with the full path of every program shown (sk8r trust).
• Your hooks are yours. Nothing is installed implicitly; an existing hook is extended, never overwritten, and sk8r's hook never blocks a commit.
• Atomic writes. Files are written through a temporary file and one replace; links and non-regular files are refused.
• No internet, no model. sk8r itself calls no online service and no AI model (the start check only talks to your own app on 127.0.0.1); package managers it runs on your behalf do go online.

Commands

Commands that write offer --dry-run; those that report offer --json. Every command and setting is in the reference; sk8r run in depth is in docs/run.md.

Configuration files

Platforms

Have a Mac? Please try sk8r and tell us how it went. The test suite passes on macOS in CI, but nobody has run it on a real Mac yet, so the Terminal.app and tmux launchers, sk8r run and the start check are unconfirmed there. A platform report takes a few minutes, and problems you hit become fixes.

Windows limit: npm-style .cmd shims such as pnpm.cmd go through batch-file parsing, so quotes and % inside their arguments can't be passed reliably; ordinary arguments are fine.

Status

sk8r 1.0 is out on PyPI. The test suite (444 tests) runs in CI on Linux, macOS and Windows with Python 3.11 and 3.15. Field results from real projects are in results. Changes are listed in the changelog.

Contributing

The easiest first contribution is a preset for a stack you use: it is a small data file plus a test. See CONTRIBUTING.md for the development setup and the checks every change passes.

License

MIT © 2026 Akash Damle