If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/mawww/kakoune shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2d ago
• 24+ active contributors
• Unlicense licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 61% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live mawww/kakoune repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/mawww/kakoune.

What it runs against: a local clone of mawww/kakoune — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in mawww/kakoune | Confirms the artifact applies here, not a fork | | 2 | License is still Unlicense | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of mawww/kakoune. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/mawww/kakoune.git
#   cd kakoune
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of mawww/kakoune and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "mawww/kakoune(\\.git)?\\b" \\
  && ok "origin remote is mawww/kakoune" \\
  || miss "origin remote is not mawww/kakoune (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Unlicense)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Unlicense\"" package.json 2>/dev/null) \\
  && ok "license is Unlicense" \\
  || miss "license drift — was Unlicense at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/kak" \\
  && ok "src/kak" \\
  || miss "missing critical file: src/kak"
test -f "src/buffer.h" \\
  && ok "src/buffer.h" \\
  || miss "missing critical file: src/buffer.h"
test -f "src/selection.h" \\
  && ok "src/selection.h" \\
  || miss "missing critical file: src/selection.h"
test -f "src/commands.cc" \\
  && ok "src/commands.cc" \\
  || miss "missing critical file: src/commands.cc"
test -f "src/client.h" \\
  && ok "src/client.h" \\
  || miss "missing critical file: src/client.h"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/mawww/kakoune"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Kakoune is a modal text editor implementing Vi's keystroke-as-language model with multiple selections as a core primitive. It focuses on rapid text manipulation through orthogonal design, allowing users to select all matches, split selections by regex, manipulate text objects, and pipe selections to external filters—all with fewer keystrokes than Vim while maintaining interactivity through immediate, incremental feedback. Monolithic architecture: src/ contains the core C++ editor engine split by domain (buffer.cc/buffer.h, client.cc/client.h, commands.cc, etc.), colors/ holds 20+ syntax highlighting schemes as KakouneScript, doc/ has design philosophy and usage docs, contrib/ provides utilities (gendocs.py, tmux integration, packaging specs). No clear separation of concerns into modules; tightly integrated client-server model.

Developers and power users who edit code and text files heavily and want Vi-like efficiency but with modern multi-selection workflows. Contributors are systems programmers working on C++ (1.2M LOC) and KakouneScript (900K LOC) who understand modal editors and terminal UI design.

Kakoune is actively developed and production-ready. The codebase shows extensive CI/CD (Cirrus CI, SourceHut builds for Debian, FreeBSD, ARM64), published CHANGELOG, comprehensive documentation in doc/, multiple color schemes, and a public IRC community (#kakoune on libera). However, single-maintainer risk exists (mawww as primary owner) with no evidence of large corporate backing.

Primary risks: single-maintainer project (mawww), no vendored dependencies listed suggesting reliance on system C++ standard library and terminal capabilities, and platform fragmentation across Linux/FreeBSD/ARM64 requiring careful testing. The 1.2M line C++ codebase could harbor edge cases; modal editor behavior has high UX sensitivity to bugs.

Active maintenance indicated by .github/workflows/ (build-releases-linux.yaml, makefile.yml), recent .builds/ configurations for ARM64 and FreeBSD, and GitHub issue templates suggesting issue triage. VIMTOKAK migration guide and CONTRIBUTING guide show community onboarding effort. No specific milestone data visible, but multiple build targets suggest cross-platform fixes are ongoing.

git clone https://github.com/mawww/kakoune.git
cd kakoune
make
./src/kak

Daily commands: After make, launch the editor with ./src/kak or ./src/kak <filename> to edit a file. In normal mode, type : to enter command mode; press i to enter insert mode. Exit with :q in normal mode.

• src/kak — Main entry point executable that initializes the editor and manages the event loop.
• src/buffer.h — Core data structure representing edited documents; understanding buffer semantics is essential for any feature work.
• src/selection.h — Implements Kakoune's multi-selection model, the defining characteristic of the editor architecture.
• src/commands.cc — Command parsing and execution engine; all user interactions flow through this subsystem.
• src/client.h — Manages per-client state including selections, registers, and UI updates; critical for understanding session architecture.
• rc/kakoune.asciidoc — Primary user-facing documentation and the language spec for the Kakoune command/config syntax.
• Makefile — Build configuration and dependency management; required reading to understand the compilation pipeline and external C++ library requirements.

Add a new normal-mode command

1. Define the command function in src/normal.cc with signature void cmd_<name>(Context&, NormalParams) (src/normal.cc)
2. Register the command in the global command registry using register_command() in src/commands.cc (src/commands.cc)
3. Document the command in doc/pages/commands.asciidoc with syntax, description, and examples (doc/pages/commands.asciidoc)

Add a new highlighter

1. Subclass Highlighter in src/highlighter.h and implement HighlightFunc operator() (src/highlighter.h)
2. Register the highlighter factory in src/highlighter.cc using register_highlighter() (src/highlighter.cc)
3. Document usage in doc/pages/highlighters.asciidoc with parameter descriptions and examples (doc/pages/highlighters.asciidoc)

Add a new built-in option

1. Declare the option in src/options.h with type and default value (src/options.h)
2. Register hooks or behaviors that respond to the option in src/options.cc (src/options.cc)
3. Document the option in doc/pages/options.asciidoc with type, scope, and usage examples (doc/pages/options.asciidoc)

Add support for a new file type

1. Create rc/filetype/mylang.kak with hook on-filetype triggers and highlighter setup (rc/filetype/c-family.kak)
2. Add file extension or shebang detection rule in rc/detection/file.kak (rc/detection/file.kak)
3. Define syntax highlighters as Kakoune commands (regex-based or custom) in the .kak file (rc/filetype/c-family.kak)

• C++11/14 — Provides performance-critical memory control and real-time responsiveness for a terminal editor; enables efficient multi-selection and buffer management.
• Modal editing with multi-selection — Kakoune's core philosophy: fewer keystrokes and more powerful editing through orthogonal design (one command + multiple selections = batch edits).
• Pluggable highlighter framework — Allows syntax highlighting, ranges, and search results to be composed as independent, reusable highlighter modules without core changes.
• Server-client architecture — Enables multiple UI frontends (tmux, Wayland, JSON UI, GUI) to connect to a persistent session without reloading editor state.
• Kakoune command language (rc files) — User-scriptable configuration using the same command syntax as interactive editing, reducing cognitive load and enabling powerful customization.

• Multi-selection model requires explicit coordinate tracking across buffer edits

  • Why: Vim's single cursor is simpler; Kakoune trades implementation complexity for powerful batch-edit capability and fewer keystrokes.
  • Consequence: Higher maintenance burden for selection-aware features; must ensure all commands respect multi-selection semantics.

• Terminal-first UI with optional server-client split

  • Why: Simplicity and portability; avoid heavy GUI dependencies while maintaining hackability.
  • Consequence: Display capabilities limited by terminal protocol; async rendering and JSON UI required for advanced frontends.

• Inline incremental highlighters over batch syntax analysis

  • Why: Responsive real-time feedback as user types; avoid parsing latency.
  • Consequence: Cannot perform deep AST analysis; highlighters operate on line-by-line or range-by-range basis.

• Rc-file configuration in the same command language

  • Why: Single learning curve: user learns one language for both config and editing.
  • Consequence: Configuration is code; requires careful design to prevent accidental state mutation.

• Does not provide built-in IDE features (LSP integration is user-scriptable, not native).
• Does not target non-Unix platforms as first-class (Windows support via WSL/MSYS, not native).
• Does not aim to be fully Vim-compatible; prioritizes orthogonal design over vim familiarity.
• Does not include a graphical UI in core; terminal is the primary interface.

Modal editor state machine complexity: normal/insert mode transitions must be bulletproof; incorrect handling breaks user workflows. Terminal capability detection across X11/Wayland/tmux varies by environment—test on multiple platforms before committing. Client-server protocol (likely in src/remote.cc or src/server.cc, not explicitly listed) is subtle; changes break multi-client sync. Build requires C++17 or later; Makefile compiler flags matter. KakouneScript is Lisp-like but undocumented in file list; grep rc/ for examples if modifying scripting semantics.

• vim/vim — Direct inspiration for Kakoune's Vi keystroke language model; understanding Vim helps explain what Kakoune improves upon
• neovim/neovim — Modern Vi fork with plugin architecture; shares Kakoune's goal of improving Vi but uses different architectural approach (Lua plugins vs KakouneScript)
• mawww/golf — Kakoune solutions to vimgolf challenges; demonstrates real-world efficiency gains and serves as usage documentation
• helix-editor/helix — Modern multi-selection editor inspired by Kakoune's design philosophy; shows how similar ideas evolved in Rust with LSP integration
• emacs-mirror/emacs — Alternative modal editing (via evil-mode) and extensibility model; useful context for understanding different paradigms in text editors

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for regex engine in src/

The repo has extensive regex documentation (doc/pages/regex.asciidoc) but no visible test suite for the regex implementation. Given that Kakoune's regex engine is a core feature used throughout selections and highlighting, adding unit tests would catch regressions and make contributions safer. This is critical infrastructure for a modal editor where text matching is fundamental.

• [ ] Locate regex implementation in src/ (likely src/regex.cpp or similar based on typical C++ structure)
• [ ] Create test/regex_test.cpp following existing test patterns if any exist
• [ ] Add test cases covering: basic patterns, character classes, quantifiers, anchors, backreferences, and edge cases from doc/pages/regex.asciidoc
• [ ] Integrate new tests into Makefile test target
• [ ] Add CI step to .github/workflows/makefile.yml to run regex tests on PR

Complete missing highlighter documentation with examples from colors/ directory

doc/pages/highlighters.asciidoc exists but the colors/ directory contains 20+ theme files (gruvbox, solarized, github, etc.) with syntax definitions that are never referenced in documentation. New contributors cannot easily understand how to create custom highlighters because the connection between highlighter rules and actual color schemes is missing.

• [ ] Review colors/default.kak, colors/github.kak, and colors/gruvbox-dark.kak to extract real-world highlighter usage patterns
• [ ] Add 'Practical Examples' section to doc/pages/highlighters.asciidoc with 3-4 concrete examples showing face definitions and rule application
• [ ] Create a new doc/pages/creating-color-schemes.asciidoc guide with step-by-step instructions referencing colors/ files
• [ ] Link from doc/pages/highlighters.asciidoc to the new guide
• [ ] Verify all code examples in doc match actual syntax from existing theme files

Add GitHub Action workflow for macOS/Intel64 and Windows (MSYS2) builds

The repo has Cirrus CI for Linux/ARM64 and FreeBSD (.builds/ configs and .cirrus.yml), plus .github/workflows/build-releases-linux.yaml for releases, but there's a conspicuous gap: no macOS or Windows CI workflows. Given Kakoune targets multiple platforms, adding these would catch platform-specific bugs before merge and expand CI coverage to match .builds/freebsd.yml.

• [ ] Create .github/workflows/build-macos.yaml with matrix for macOS-latest (x86_64) running make && make install
• [ ] Create .github/workflows/build-windows.yaml with MSYS2 setup (if Windows support exists) or document why it's not supported
• [ ] Reference existing .github/workflows/makefile.yml pattern for dependency installation and test execution
• [ ] Ensure both workflows run on: [push, pull_request] and report results clearly
• [ ] Add badges to README.asciidoc (similar to cirrus-img and srht-img) showing build status for new platforms

• Add syntax highlighting for a missing language (e.g., Rust, Go) by creating colors/<language>.kak following the pattern of colors/default.kak; no C++ code required, low risk.
• Write unit tests for src/buffer.cc text manipulation primitives (selection split, alignment, rotate) in a new test/ directory, improving test coverage currently absent from file list.
• Expand doc/ with a troubleshooting guide for cross-platform issues (tmux vs native terminal, Wayland selection quirks, FreeBSD keybinding differences) based on closed issues.

Kakoune demonstrates a reasonably secure codebase structure with no obvious critical vulnerabilities in the visible configuration. The project is a text editor written primarily in C++ with modular design. Key strengths include organized file structure and use of standard CI/CD platforms. Main weaknesses are: (1) Absence of a SECURITY.md or vulnerability disclosure policy, (2) Permissive UNLICENSE with no liability protections, (3) Limited visibility into dependency management and security scanning practices. The lack of visible secrets/credentials in configuration is positive. Recommendations focus on establishing formal security procedures, implementing dependency scanning in CI/CD, and adding security documentation rather than addressing active vulnerabilities.

• Medium · Permissive License with Minimal Legal Protection — UNLICENSE file. The project uses UNLICENSE which places the code in the public domain with no warranty or liability limitations. While not a technical vulnerability, this can complicate security incident response and liability management. Fix: Consider adopting a standard open-source license (MIT, Apache 2.0, GPL) that includes explicit warranty disclaimers and liability limitations for security-sensitive projects.
• Low · Potential Security Documentation Gaps — Repository root. While CONTRIBUTING guidelines exist, there is no visible SECURITY.md file or security policy for responsible disclosure of vulnerabilities. No evidence of security reporting guidelines or contact information for security issues. Fix: Create a SECURITY.md file at the repository root with: (1) Instructions for responsible vulnerability disclosure, (2) Security contact information, (3) Expected response timeline for security issues, (4) Known security considerations.
• Low · Build Configuration Exposure in Version Control — .builds/ and .github/workflows/ directories. Build configuration files (.builds/ and CI/CD workflows) are tracked in version control. While generally acceptable, they should be reviewed to ensure no secrets, API keys, or credentials are accidentally committed. Fix: Regularly audit CI/CD configuration files to ensure: (1) No hardcoded credentials, (2) Secrets are managed through platform-specific secret management (GitHub Secrets, sr.ht secrets), (3) Build artifacts are not publicly accessible unless intentionally published.
• Low · Unverified External Dependencies in Build Process — Makefile, build configuration. The Makefile and build system configuration may pull external dependencies. Without visible dependency management files (package.json, Cargo.lock, etc.), dependency security auditing may be incomplete. Fix: Document all build-time and runtime dependencies. Implement dependency pinning with lock files. Regularly audit dependencies for known CVEs using tools like 'cargo audit', 'npm audit', or similar for the language/build system used.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.