Contribute

Fork Kunai, run tests, opt into live provider smokes, and open PRs with evidence.

Who this guide is for

Contributors changing the Kunai CLI, providers, or documentation who want a reviewable PR with clear evidence.

You will learn: how to fork the repo, verify the baseline, run the right tests, attach diagnostics for playback or provider bugs, and stay inside project boundaries.

Thank you for contributing. Kunai is Bun-first, terminal-first, and evidence-driven — PRs with reproduction steps or test coverage are easier to review.

Before you start

Read the repo entry points:

CLAUDE.md / AGENTS.md — routing, hard boundaries, commands
.docs/architecture.md — playback flow and data ownership (in-repo deep doc, not published on this site)
Debugging workflow — traces and diagnostics for bug reports

Provider changes need extra care

Before changing provider crypto, decoder constants, or AllManga/AllAnime parity logic, compare against the local ani-cli reference checkout documented in CLAUDE.md. Provider modules live in packages/providers/src/*/direct.ts; the production registry is wired in apps/cli/src/container/bootstrap-providers.ts.

Fork and setup

Fork and clone

git clone https://github.com/YOUR_USER/kunai.git
cd kunai

Install dependencies

bun install

Bun is the supported runtime for development. Use bun run dev -- <flags> to launch the CLI from source.

Link globally (optional)

bun run link:global
kunai --setup

Verify the baseline

bun run typecheck
bun run lint
bun run test

All three should pass before you open a PR. Run bun run fmt if formatting fails.

Project layout (quick map)

Path	Purpose
`apps/cli/src/main.ts`	Canonical CLI entrypoint
`apps/cli/src/app-shell/`	Ink shell, command bar, overlays
`apps/cli/src/container/bootstrap-providers.ts`	Production provider registry
`packages/providers/`	Direct provider modules
`packages/storage/`	SQLite history, cache, downloads
`apps/cli/test/unit/`	Unit tests
`apps/cli/test/integration/`	Integration tests
`apps/cli/test/live/`	Opt-in live provider smokes
`docs/`	User and developer documentation (this site)

Running tests

bun run test           # full test suite (preferred entry)
bun run typecheck      # TypeScript across monorepo
bun run lint           # ESLint
bun run fmt            # format check
bun run build          # release build — run before large features

Unit tests live under apps/cli/test/unit/. Integration tests under apps/cli/test/integration/. Do not use bun test directly — use bun run test.

Docs changes:

bun run --cwd apps/docs generate
bun run --cwd apps/docs typecheck:app
bun run --cwd apps/docs test
bun run --cwd apps/docs build:app

See Docs maintenance.

Live provider smokes (opt-in)

Live tests hit real provider endpoints. They are manual release checks — not default CI.

bun run test:live:videasy
bun run test:live:vidking   # alias for videasy
bun run test:live:rivestream
bun run test:live:allanime "Kimetsu no Yaiba" SJms742bSTrcyJZay
bun run test:live:miruro

Each smoke creates an isolated temp profile under /tmp/kunai-live-*. Do not run live smokes in a tight loop while debugging — use unit tests and --debug-json traces for iteration, then one live smoke to confirm provider reality.

Use KITSUNE_CLEAR_CACHE=1 only when you need a cold-cache proof.

Debugging your change

# Structured trace
KUNAI_TRACE=provider,playback,cache bun run dev -- -S "Dune" --debug-json

# Full session trace
bun run dev -- -S "Dune" --debug-session

# Breakpoint debugging
bun --inspect-brk apps/cli/src/main.ts --debug-session -S "Dune"

Inside the shell: /diagnostics, /export-diagnostics. See Debugging workflow.

PR expectations

Scope and style

Minimize diff scope — one logical change per PR when possible.
Match surrounding naming, types, and patterns.
Extract shared logic when duplicate code would smell across files.
Do not add noisy console.log in Ink render paths — use diagnostics events.

Required checks

Before requesting review:

bun run fmt
bun run lint
bun run typecheck
bun run test

Run bun run build for features that touch build-only paths or release packaging.

PR description should include

What changed (user-visible behavior first).
Why — bug fix, provider drift, UX gap, etc.
How to test — exact commands and flags.
Evidence — diagnostics bundle path, trace excerpt, or test output for provider/playback changes.

Provider PRs additionally

Note which live smoke you ran (if any).
Do not register candidate providers in bootstrap-providers.ts until they pass the quality gate.
Document temporary divergence from ani-cli parity in provider docs or plans when unavoidable.

Docs PRs

User-facing behavior before implementation detail.
Use /docs/users/... absolute paths for internal links — never ../../.docs or ../../.plans.
Register new pages in the nearest meta.json.
Run bun run --cwd apps/docs generate when commands or providers change.

Hard boundaries (do not violate)

apps/cli/index.ts is a compatibility wrapper — new runtime work goes in apps/cli/src/main.ts.
Episode numbers are 1-based in the UI.
Browser/Playwright legacy code is archive reference only — not active beta runtime.
Diagnostics exports must not include raw stream URLs, tokens, or private home paths.
Do not commit secrets (.env, tokens, session captures).

Getting help

Open a draft PR early for large changes.
Attach redacted /export-diagnostics bundles to issue reports.
Use /report-issue from Kunai for the guided GitHub flow.

Docs maintenance — add pages, codegen, drift tests
Debugging workflow — symptom triage for developers
Supported and unsupported — beta scope boundaries

Who this guide is for

Contributors changing the Kunai CLI, providers, or documentation who want a reviewable PR with clear evidence.

You will learn: how to fork the repo, verify the baseline, run the right tests, attach diagnostics for playback or provider bugs, and stay inside project boundaries.

Thank you for contributing. Kunai is Bun-first, terminal-first, and evidence-driven — PRs with reproduction steps or test coverage are easier to review.

Before you start

Read the repo entry points:

CLAUDE.md / AGENTS.md — routing, hard boundaries, commands
.docs/architecture.md — playback flow and data ownership (in-repo deep doc, not published on this site)
Debugging workflow — traces and diagnostics for bug reports

Provider changes need extra care

Fork and setup

Fork and clone

git clone https://github.com/YOUR_USER/kunai.git
cd kunai

Install dependencies

bun install

Bun is the supported runtime for development. Use bun run dev -- <flags> to launch the CLI from source.

Link globally (optional)

bun run link:global
kunai --setup

Verify the baseline

bun run typecheck
bun run lint
bun run test

All three should pass before you open a PR. Run bun run fmt if formatting fails.

Project layout (quick map)

Path	Purpose
`apps/cli/src/main.ts`	Canonical CLI entrypoint
`apps/cli/src/app-shell/`	Ink shell, command bar, overlays
`apps/cli/src/container/bootstrap-providers.ts`	Production provider registry
`packages/providers/`	Direct provider modules
`packages/storage/`	SQLite history, cache, downloads
`apps/cli/test/unit/`	Unit tests
`apps/cli/test/integration/`	Integration tests
`apps/cli/test/live/`	Opt-in live provider smokes
`docs/`	User and developer documentation (this site)

Running tests

bun run test           # full test suite (preferred entry)
bun run typecheck      # TypeScript across monorepo
bun run lint           # ESLint
bun run fmt            # format check
bun run build          # release build — run before large features

Unit tests live under apps/cli/test/unit/. Integration tests under apps/cli/test/integration/. Do not use bun test directly — use bun run test.

Docs changes:

bun run --cwd apps/docs generate
bun run --cwd apps/docs typecheck:app
bun run --cwd apps/docs test
bun run --cwd apps/docs build:app

See Docs maintenance.

Live provider smokes (opt-in)

Live tests hit real provider endpoints. They are manual release checks — not default CI.

bun run test:live:videasy
bun run test:live:vidking   # alias for videasy
bun run test:live:rivestream
bun run test:live:allanime "Kimetsu no Yaiba" SJms742bSTrcyJZay
bun run test:live:miruro

Use KITSUNE_CLEAR_CACHE=1 only when you need a cold-cache proof.

Debugging your change

# Structured trace
KUNAI_TRACE=provider,playback,cache bun run dev -- -S "Dune" --debug-json

# Full session trace
bun run dev -- -S "Dune" --debug-session

# Breakpoint debugging
bun --inspect-brk apps/cli/src/main.ts --debug-session -S "Dune"

Inside the shell: /diagnostics, /export-diagnostics. See Debugging workflow.

PR expectations

Scope and style

Minimize diff scope — one logical change per PR when possible.
Match surrounding naming, types, and patterns.
Extract shared logic when duplicate code would smell across files.
Do not add noisy console.log in Ink render paths — use diagnostics events.

Required checks

Before requesting review:

bun run fmt
bun run lint
bun run typecheck
bun run test

Run bun run build for features that touch build-only paths or release packaging.

PR description should include

What changed (user-visible behavior first).
Why — bug fix, provider drift, UX gap, etc.
How to test — exact commands and flags.
Evidence — diagnostics bundle path, trace excerpt, or test output for provider/playback changes.

Provider PRs additionally

Note which live smoke you ran (if any).
Do not register candidate providers in bootstrap-providers.ts until they pass the quality gate.
Document temporary divergence from ani-cli parity in provider docs or plans when unavoidable.

Docs PRs

User-facing behavior before implementation detail.
Use /docs/users/... absolute paths for internal links — never ../../.docs or ../../.plans.
Register new pages in the nearest meta.json.
Run bun run --cwd apps/docs generate when commands or providers change.

Hard boundaries (do not violate)

apps/cli/index.ts is a compatibility wrapper — new runtime work goes in apps/cli/src/main.ts.
Episode numbers are 1-based in the UI.
Browser/Playwright legacy code is archive reference only — not active beta runtime.
Diagnostics exports must not include raw stream URLs, tokens, or private home paths.
Do not commit secrets (.env, tokens, session captures).

Getting help

Open a draft PR early for large changes.
Attach redacted /export-diagnostics bundles to issue reports.
Use /report-issue from Kunai for the guided GitHub flow.

Docs maintenance — add pages, codegen, drift tests
Debugging workflow — symptom triage for developers
Supported and unsupported — beta scope boundaries

Contribute

On this page

Contribute

On this page