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/trogdoro/xiki 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.

AVOID — Looks unmaintained — solo project with stale commits

• Other licensed
• Tests present
• ⚠ Stale — last commit 6y ago
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected

_{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 trogdoro/xiki repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/trogdoro/xiki.

What it runs against: a local clone of trogdoro/xiki — 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 trogdoro/xiki | Confirms the artifact applies here, not a fork | | 2 | License is still Other | 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 ≤ 2349 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of trogdoro/xiki. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/trogdoro/xiki.git
#   cd xiki
#
# 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 trogdoro/xiki and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other 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 "lib/xiki.rb" \\
  && ok "lib/xiki.rb" \\
  || miss "missing critical file: lib/xiki.rb"
test -f "lib/xiki/core/invoker.rb" \\
  && ok "lib/xiki/core/invoker.rb" \\
  || miss "missing critical file: lib/xiki/core/invoker.rb"
test -f "lib/xiki/core/menu.rb" \\
  && ok "lib/xiki/core/menu.rb" \\
  || miss "missing critical file: lib/xiki/core/menu.rb"
test -f "lib/xiki/core/expander.rb" \\
  && ok "lib/xiki/core/expander.rb" \\
  || miss "missing critical file: lib/xiki/core/expander.rb"
test -f "lib/xiki/handlers/menu_handler.rb" \\
  && ok "lib/xiki/handlers/menu_handler.rb" \\
  || miss "missing critical file: lib/xiki/handlers/menu_handler.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 2349 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2319d)"
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/trogdoro/xiki"
  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).

Xiki is an interactive shell console framework written in Ruby that augments bash/zsh with tree-structured menus, GUI-like navigation, and command expansion features. It lets users interact with the command line through hierarchical, clickable/expandable menu trees instead of pure text, making complex operations more discoverable and interactive. Monolithic structure: lib/xiki.rb is the entry point, with all functionality in lib/xiki/core/ split by feature (menu.rb, expander.rb, command.rb, file_tree.rb, etc.). The bin/ directory contains CLI entry points (xsh, xiki, xikigem). Heavy Emacs Lisp integration in a separate dir suggests dual-editor support (Emacs + potential other editors).

DevOps engineers, system administrators, and power shell users who want faster command discovery and navigation without leaving the terminal; developers who want to build custom interactive CLI menus and shell tools with minimal friction.

Active but niche: the repo has substantial code (~1.6M lines of Ruby) and supports multiple platforms (macOS, Linux) with a documented install process, but appears to be maintained by a single core contributor (@trogdoro). The presence of a tutorial and chat community suggests production use, but the small feature set in lib/xiki/core/ and lack of visible CI/test output suggests experimental maturity.

Single-maintainer project with no visible test suite in the file listing, no CI configuration mentioned, and unclear dependency management (Gemfile exists but not shown). The core functionality is tightly coupled to Emacs Lisp integration (47K lines) and shell-specific logic, making it fragile to shell version changes. No visible recent commit data, so activity status is unclear.

No recent activity data visible from the repo snapshot. The README mentions tutorial and help commands (xsh --tutorial, xsh --help), suggesting the project is feature-complete but not actively evolving. The mention of a 'xsh forker' process suggests performance optimization work was done at some point.

git clone https://github.com/trogdoro/xiki.git && cd xiki && ./install OR curl -L https://xiki.com/install_xsh -o ~/install_xsh && bash ~/install_xsh. Then run xsh or xsh --tutorial from the command line.

Daily commands: bin/xsh starts the interactive shell. For development: Ruby must be installed with Bundler (Gemfile present). Run ./install from repo root to set up, or bin/xsh directly to test.

• lib/xiki.rb — Main entry point that loads and orchestrates the entire Xiki framework and its core modules.
• lib/xiki/core/invoker.rb — Core request execution engine that interprets menu trees and dispatches to handlers, fundamental to Xiki's command processing.
• lib/xiki/core/menu.rb — Menu abstraction layer that parses and manages tree-structured commands, core to Xiki's tree-based UI paradigm.
• lib/xiki/core/expander.rb — Expands tree nodes and executes menu items, central to interactive tree navigation and menu rendering.
• lib/xiki/handlers/menu_handler.rb — Router that dispatches requests to appropriate handlers (shell, ruby, dir, etc.) based on file type and context.
• bin/xsh — Command-line executable entry point that initializes the Xiki Shell and provides user interface to the framework.
• lib/xiki/core/shell.rb — Shell integration layer that manages command execution, output capture, and environment interaction for system commands.

Add a new menu handler for a file type

1. Create a new handler class in lib/xiki/handlers/ following the naming convention *_handler.rb (lib/xiki/handlers/custom_handler.rb)
2. Implement the handler to respond to file paths and return formatted menu items (lib/xiki/handlers/custom_handler.rb)
3. Register the handler in lib/xiki/handlers/menu_handler.rb by adding a conditional check for the file type (lib/xiki/handlers/menu_handler.rb)

Add a new core module or feature

1. Create a new module file in lib/xiki/core/ with a descriptive name (lib/xiki/core/new_feature.rb)
2. Define the module with methods that follow Xiki's conventions for menu item expansion (lib/xiki/core/new_feature.rb)
3. Require the module in lib/xiki.rb to ensure it loads with the framework (lib/xiki.rb)
4. Optionally register key bindings in lib/xiki/core/keys.rb if the feature needs keyboard shortcuts (lib/xiki/core/keys.rb)

Add support for a new menu tree source (e.g., REST API, database)

1. Create a new tree handler in lib/xiki/core/ (e.g., rest_tree.rb, url_tree.rb provide examples) (lib/xiki/core/custom_tree.rb)
2. Implement methods to fetch and format data as tree menu items (lib/xiki/core/custom_tree.rb)
3. Register the tree type in lib/xiki/handlers/menu_handler.rb to route requests appropriately (lib/xiki/handlers/menu_handler.rb)
4. Add tests or examples demonstrating the new tree source (lib/xiki/core/index.menu)

Add a new keyboard shortcut or command

1. Define the command logic in an appropriate core module (or create a new one) (lib/xiki/core/new_command.rb)
2. Register the key binding in lib/xiki/core/keys.rb with the desired shortcut and handler (lib/xiki/core/keys.rb)
3. Optionally add command documentation to lib/xiki/core/command.rb for discoverability (lib/xiki/core/command.rb)

• Ruby — DSL-friendly language enables expressive menu definitions; metaprogramming supports dynamic handler registration and code-driven trees
• Shell integration (bash/zsh) — Allows Xiki to augment existing shell workflows without replacing them; xsh wrapper layer preserves native shell capabilities
• Tree-based menu paradigm — Hierarchical structure mirrors file systems and command hierarchies; enables progressive disclosure and intuitive navigation
• Handler pattern — Decouples menu sources (files, shell commands, Ruby objects, REST APIs) from execution logic; allows extensibility without core changes

• Interpreted Ruby execution for menu items vs. compiled approach

  • Why: Enables rapid prototyping and interactive REPL-style workflow; allows users to define menus inline
  • Consequence: Slower execution for large menu trees; potential security concerns with arbitrary code execution

• Tight coupling with shell UI vs. pure programmatic API

  • Why: Provides immediate visual feedback and interactive experience; leverages existing terminal familiarity
  • Consequence: Less suitable for headless/batch processing; harder to embed in non-interactive contexts

• Multiple handler types (shell, Ruby, ERB, Markdown) vs. single unified format

  • Why: Lets users work in their preferred language/format; reduces friction for different use cases
  • Consequence: Increased complexity; harder to reason about menu behavior across different sources

• Provide a real-time graphical user interface (designed for terminal/shell environment only)
• Handle enterprise authentication or role-based access control
• Support non-Unix-like shells (bash/zsh focused)
• Provide

The 'xsh forker' process mentioned in README is a persistent daemon that must be running for performance; if it hangs, the CLI can appear frozen—use ps aux|grep forker and kill it. Xiki is tightly integrated with Emacs Lisp (47K lines), so non-Emacs users may hit uncovered code paths. Install script expects bash/zsh and modifies shell config files—manual setup required if not using standard setup. No visible dependency list means Ruby version compatibility is unclear.

• Tree expansion / lazy evaluation — Xiki's core abstraction is expanding menu trees on demand; expander.rb likely implements a pull-based tree evaluation pattern where nodes are expanded only when accessed, crucial for performance on large file systems or command trees
• Menu-driven CLI (WIMP for terminals) — Xiki brings GUI-like menu paradigms (click, expand, navigate) to the shell; understanding this shift from text commands to hierarchical selection is core to why xiki exists
• Shell process forking and persistence (xsh forker) — Xiki maintains a forked background process to speed up command execution; understanding process lifecycle, signal handling, and IPC is critical for debugging the 'frozen forker' problem and understanding performance characteristics
• Editor integration via scripts (Emacs Lisp + Ruby bridge) — Xiki is dual-interface (shell + Emacs); the 47K lines of .el code and Ruby integration mean you need to understand how Ruby calls Emacs and vice versa, and how state syncs between them
• Stdin/stdout redirection and piping chains — Many lib/xiki/core modules (command.rb, files.rb, clipboard.rb) manipulate shell I/O streams; Xiki acts as a filter/dispatcher between user input and shell output
• Context-aware command completion and suggestion — command_suggester.rb and key_shortcuts.rb implement context-sensitive command hints; this is how xiki surfaces the right commands at the right time without overwhelming the user
• File path and tree traversal algorithms — file_tree.rb and dirs.rb implement efficient directory traversal; understanding how xiki caches or lazy-loads directory contents avoids N+1 file system calls

• junegunn/fzf — Similar goal (interactive CLI navigation) but uses fuzzy-find instead of menu trees; many xiki users also use fzf for complementary workflows
• denisidoro/navi — Interactive CLI cheat sheet and command runner; overlaps with xiki's goal of making command discovery easier
• sharkdp/fzt — Fast terminal tree browser; xiki's file_tree.rb serves a similar niche but with more integration
• oh-my-zsh/oh-my-zsh — Popular zsh framework with plugins; xiki complements zsh by adding structured menu navigation at a layer above shell aliases/functions
• trogdoro/xiki-el — The Emacs Lisp half of xiki; repo likely contains the 47K lines of .el code for Emacs integration that pairs with this Ruby core

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 test suite for lib/xiki/core/expander.rb and lib/xiki/core/invoker.rb

These two core modules handle the critical functionality of expanding menu items and invoking commands. Currently there's no evidence of test files in the repo structure. Adding unit tests for the expansion logic (handling nested menus, parameter substitution) and invocation logic (command execution, output handling) would catch regressions and make contributions safer. This is especially important given the complexity of menu expansion which appears throughout the codebase.

• [ ] Create test/xiki/core/test_expander.rb with tests for menu expansion, recursion, and parameter handling
• [ ] Create test/xiki/core/test_invoker.rb with tests for command execution paths and output capture
• [ ] Add Rakefile task to run tests (rake test or similar)
• [ ] Document test setup in CONTRIBUTING.md or update README with testing instructions

Add GitHub Actions CI workflow for Ruby version compatibility and linting

The repo has a Gemfile suggesting dependency management, but no visible CI configuration. Adding a GitHub Actions workflow would catch breaking changes across Ruby versions (especially important since xiki supports shell integration). This should test against multiple Ruby versions (2.7+, 3.0+) and run rubocop or similar linting on the lib/xiki/core files to maintain code quality standards.

• [ ] Create .github/workflows/ci.yml with matrix testing for Ruby 2.7, 3.0, 3.1, 3.2
• [ ] Include rake test or similar test command execution
• [ ] Add rubocop linting step targeting lib/xiki/core directory
• [ ] Add workflow status badge to README.md

Create missing API documentation for core modules in lib/xiki/core

The codebase has 50+ core modules (menu.rb, command.rb, path.rb, files.rb, git.rb, etc.) but the README only mentions basic xsh usage. New contributors cannot easily understand what each module does or how they interact. Creating a modular documentation file would list each core module with its primary responsibility and key public methods.

• [ ] Create docs/CORE_MODULES.md documenting each lib/xiki/core/*.rb file (purpose, key classes/methods)
• [ ] Group modules by category: navigation (path.rb, location.rb, dirs.rb), editing (insert.rb, deletes.rb, block.rb), command execution (command.rb, invoker.rb, expander.rb), and UI (menu.rb, overlay.rb, message.rb)
• [ ] Add code examples for the 5-10 most commonly extended modules
• [ ] Link CONTRIBUTING.md to this documentation for new contributor onboarding

• Add a test suite: lib/xiki/core/*.rb has no visible spec/ or test/ directory. Create spec/lib/xiki/core/menu_spec.rb to test menu parsing with common cases (nested trees, expansion, command dispatch).
• Document the menu.rb and expander.rb interaction: no visible docs on how menu.rb delegates to expander.rb or how tree nodes are expanded. Add inline YARD docs and a doc/architecture.md explaining the expansion pipeline.
• Add integration tests for bin/xsh: verify that xsh --tutorial and xsh --help output correct content, and that a simple command through xsh produces expected output. Shell tests are rare in the codebase.

• High · Outdated Docker Base Image — Dockerfile (line 1). The Dockerfile uses 'ubuntu:16.04' which reached end-of-life in April 2021. This base image no longer receives security updates, exposing the container to known vulnerabilities in system packages including Ruby, Git, and Emacs. Fix: Update to a supported Ubuntu LTS version such as 'ubuntu:22.04' or 'ubuntu:20.04' and rebuild all dependencies.
• High · Missing Package Pinning in Docker — Dockerfile (lines 3-11). The Dockerfile uses 'apt-get install -y' without specifying package versions. This can lead to non-deterministic builds where different versions are installed at different times, potentially including vulnerable package versions. Fix: Pin specific versions for all packages: 'apt-get install -y package=version' to ensure reproducible and secure builds.
• Medium · No Dependency Lock File Provided — Gemfile (contents not visible). While a Gemfile is referenced in the repository structure, its contents were not provided. Without a Gemfile.lock, Ruby dependencies are not pinned to specific versions, creating potential supply chain risks from transitive dependency updates. Fix: Ensure Gemfile.lock is committed to version control and that 'bundle install --frozen' is used in production deployments to lock all dependency versions.
• Medium · Unsafe Curl Installation Pattern — README.md and install_xsh script. The README recommends piping curl directly to bash: 'curl -L https://xiki.com/install_xsh -o ~/install_xsh; bash ~/install_xsh'. This is a well-known security anti-pattern vulnerable to man-in-the-middle attacks and remote code execution. Fix: Provide SHA256 checksums for downloaded files, use HTTPS verification, and recommend users to inspect the script before execution. Consider using package managers (apt, brew, etc.) for distribution.
• Medium · Shell Injection Risk in Shell Integration — lib/xiki/core/shell.rb, lib/xiki/core/command.rb, lib/xiki/core/invoker.rb. The project heavily integrates with shell execution (bin/xsh, bin/xikigem, lib/xiki/core/shell.rb, lib/xiki/core/command.rb). Without visible input validation patterns, there is significant risk of shell injection if user input is passed to system commands without proper escaping. Fix: Conduct thorough code review of all shell execution patterns. Use parameterized command execution (e.g., system with array form) rather than string interpolation. Implement strict input validation and whitelisting.
• Medium · No Input Sanitization Visible in File Processing — lib/xiki/core/file_tree.rb, lib/xiki/core/path.rb, lib/xiki/core/tree.rb. Files like lib/xiki/core/file_tree.rb, lib/xiki/core/path.rb, and lib/xiki/core/tree.rb suggest file path manipulation. Without visible sanitization, path traversal attacks (e.g., '../../../') could be possible. Fix: Implement strict path validation, normalize paths, and use File.expand_path with base directory constraints. Reject paths containing '..' or symbolic links that escape intended directories.
• Low · Git Repository in Docker Build Context — Dockerfile (line 13). The Dockerfile copies the entire working directory (COPY . /xiki/) which may include .git directory containing repository history, sensitive branch information, or previous commits with secrets. Fix: Add '.git' to .gitignore for Docker builds, or use .dockerignore file to exclude sensitive directories. Consider using Docker multi-stage builds to minimize final image size and exposure.
• Low · Missing Security Headers and Isolation — Dockerfile (CMD directive). The container runs as root without capability restrictions or read-only filesystem options, and no security-related Docker run flags are documented. Fix: Run the container with restricted privileges: use USER directive to run as non-root, apply security options like '--cap-drop=ALL', '--read-only', and '--security-opt=no-new-privileges'.
• undefined · undefined — undefined. undefined Fix: undefined

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.