Onboarding: microsoft/inshellisense

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

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/microsoft/inshellisense 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.

Verdict

GO — Healthy across all four use cases

• Last commit 2d ago
• 9 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 92% of recent commits

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

Verify before trusting

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

What it runs against: a local clone of microsoft/inshellisense — 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 microsoft/inshellisense | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main 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 |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>microsoft/inshellisense</code></summary>

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

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

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

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

# 4. Critical files exist
test -f "src/index.ts" \\
  && ok "src/index.ts" \\
  || miss "missing critical file: src/index.ts"
test -f "src/isterm/index.ts" \\
  && ok "src/isterm/index.ts" \\
  || miss "missing critical file: src/isterm/index.ts"
test -f "src/runtime/runtime.ts" \\
  && ok "src/runtime/runtime.ts" \\
  || miss "missing critical file: src/runtime/runtime.ts"
test -f "src/ui/ui-root.ts" \\
  && ok "src/ui/ui-root.ts" \\
  || miss "missing critical file: src/ui/ui-root.ts"
test -f "src/commands/root.ts" \\
  && ok "src/commands/root.ts" \\
  || miss "missing critical file: src/commands/root.ts"

# 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/microsoft/inshellisense"
  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).

</details>

TL;DR

inshellisense is a terminal-native IDE-style autocomplete runtime that provides real-time command suggestions for 600+ CLI tools across bash, zsh, fish, PowerShell, nushell, and xonsh. It integrates the @withfig/autocomplete spec library (v2.675.0) into a pseudo-terminal (via node-pty) and renders suggestions using xterm.js, replacing the traditional static man-page help experience with interactive, context-aware completions. Monolithic TypeScript application: src/commands/ contains CLI entry points (complete.ts, init.ts, doctor.ts, uninstall.ts), src/isterm/ manages the pseudo-terminal and PTY lifecycle (pty.ts, commandManager.ts), src/runtime/ handles alias resolution and spec generation (alias.ts, generator.ts). Shell integration scripts live in shell/ directory (shell/shellIntegration.bash, shell/shellIntegration.zsh, etc.) and are injected into user shell configs. Built to build/ via TypeScript compilation.

Who it's for

DevOps engineers, systems administrators, and power shell users who spend significant time in terminals and want IDE-grade autocomplete (like VSCode IntelliSense) without leaving their shell. Contributors are primarily Microsoft maintainers extending shell integration scripts and completion generators.

Maturity & risk

Actively maintained and production-ready: published on npm (@microsoft/inshellisense), available via Homebrew, has multi-shell support with CI/CD pipelines (ci.yml, pkg.yml), and includes test infrastructure (jest.config.cjs). Version is 0.0.1 (pre-1.0) suggesting it may still be stabilizing core APIs, but the breadth of shell support and packaging indicate real-world usage.

Low-risk dependencies (xterm, ansi-escapes, commander, node-pty are mature), but depends critically on @withfig/autocomplete specs which is a third-party library maintained by withfig.com—if that spec collection stagnates or breaks, completions degrade. Single maintainer risk is present (Microsoft author, but small team). Node version constraint (>=18 <23.0.0) may require updates as Node LTS advances. Integration with shell init files (.bashrc, .zshrc, etc.) is fragile—user config ordering can break loading per the README warning.

Active areas of work

No PR or milestone data visible in file list, but the 0.0.1 version and presence of reinit command suggest ongoing stabilization. CI pipelines (ci.yml for testing, pkg.yml for packaging) are active. Focus appears to be on expanding shell support (Nushell, Xonsh scripts present) and improving the doctor command for diagnostics.

Get running

git clone https://github.com/microsoft/inshellisense.git
cd inshellisense
npm install
npm run build
node build/index.ts init bash  # or zsh/fish/pwsh/nu/xsh

Daily commands:

# Development
npm run build && node --import=tsx src/index.ts -V

# Or directly with tsx
npm run dev

# Debugging
npm run debug  # runs with --inspect for debugger attach

# Tests
npm test
npm run test:e2e  # TUI integration tests

Map of the codebase

• src/index.ts — Main entry point; orchestrates CLI commands and initialization logic for the entire application
• src/isterm/index.ts — Core terminal integration layer that manages PTY sessions and command execution for autocomplete
• src/runtime/runtime.ts — Central runtime engine that parses shell state, manages aliases, and generates completion suggestions
• src/ui/ui-root.ts — Main UI orchestrator that coordinates the suggestion manager and terminal interaction during autocomplete sessions
• src/commands/root.ts — CLI command router that dispatches to init, complete, doctor, and other subcommands
• src/runtime/parser.ts — Parses shell command lines and extracts tokens for completion; critical for suggestion accuracy
• src/isterm/pty.ts — PTY wrapper managing pseudo-terminal communication with shells across Windows, macOS, and Linux

How to make changes

Add Support for a New Shell

1. Create a new shell integration script in shell/ directory (e.g., shell/shellIntegration-xyzsh.zsh) that exports PS1/PROMPT and calls the inshellisense binary via a hook (shell/shellIntegration.bash)
2. Update src/utils/shell.ts to detect the new shell type in getShell() and getShellPath() functions (src/utils/shell.ts)
3. Update src/commands/init.ts to inject the new shell script during is init for the detected shell (src/commands/init.ts)
4. Add test fixtures and test cases in src/tests/ to verify parser and runtime behavior for the new shell's syntax (src/tests/runtime/parser.test.ts)

Add a New Completion Spec or Generator Rule

1. Create or update a completion spec JSON/YAML file in the specs directory (specs are loaded via src/utils/config.ts) (src/commands/specs/list.ts)
2. Extend src/runtime/generator.ts to handle new spec properties (e.g., custom argument resolution, conditional subcommands) (src/runtime/generator.ts)
3. Add test cases in src/tests/runtime/runtime.test.ts to verify suggestion generation for the new spec (src/tests/runtime/runtime.test.ts)

Enhance the UI or Suggestion Filtering

1. Modify src/ui/suggestionManager.ts to implement new filtering, ranking, or rendering logic (src/ui/suggestionManager.ts)
2. Update src/ui/utils.ts with new formatting or layout helper functions as needed (src/ui/utils.ts)
3. Add or update UI tests in src/tests/ui/ to validate the new rendering behavior (src/tests/ui/autocomplete.test.ts)

Add a New CLI Command

1. Create a new command file in src/commands/ (e.g., src/commands/mycommand.ts) that exports a handler function (src/commands/init.ts)
2. Register the command in src/commands/root.ts by adding a branch to the command router (src/commands/root.ts)
3. Create a corresponding UI file in src/ui/ui-mycommand.ts if the command requires interactive prompts or output formatting (src/ui/ui-init.ts)
4. Add tests in src/tests/ to verify command execution and output (src/tests/runtime/runtime.test.ts)

Why these technologies

• TypeScript + Node.js — Cross-platform runtime; type safety for complex shell parsing logic; npm ecosystem for CLI tools
• PTY (node-pty or similar) — Enables pseudo-terminal communication with shells for capturing state and executing context commands
• JSON/YAML specs (autocomplete format) — Declarative completion definitions; enables reuse of 600+ existing community specs from withfig/autocomplete
• Shell integration scripts (bash/zsh/fish/pwsh) — Hooks into native shell prompt evaluation to trigger inshellisense without modifying user shell binaries
• Jest + snapshot testing — Validates parser output and runtime behavior; snapshots catch regressions in completion logic

Trade-offs already made

• Shell integration via injected scripts rather than shell builtins

  • Why: Maximizes compatibility across shell versions and avoids requiring shell source modifications
  • Consequence: Users must run 'is init' to inject hooks; uninstall requires script cleanup

• Separate PTY session for context collection vs. inline shell state

  • Why: Avoids blocking the user's active shell and provides isolated environment for running auxiliary commands
  • Consequence: Context may lag slightly behind current shell state; requires extra process overhead

• Client-side suggestion generation vs. server-based completion

  • Why: Offline-first approach; no network dependency for autocomplete; all specs bundled locally
  • Consequence: Larger on-disk footprint; spec updates require reinstallation or manual refresh

• Parse shell syntax (aliases, variable expansion) vs. defer to shell evaluation

  • Why: Provides instant suggestions without shell round-trips; enables offline context inference
  • Consequence: Parser may diverge from shell semantics; complex expansions may not resolve correctly

Non-goals (don't propose these)

• Real-time collaborative editing or multi-user shell sessions
• Custom spec creation UI or GUI (spec format is JSON/YAML only)

Traps & gotchas

Shell integration injection risk: README warns that init commands must be last in shell config—commands after the plugin will break because inshellisense wraps the shell environment. PTY compatibility: node-pty is v1.2.0-beta.8 (pre-release)—may have undocumented behaviors on Windows or newer Node versions. Spec staleness: completion specs come from @withfig/autocomplete v2.675.0—if user's CLI tool version doesn't match the spec, suggestions will be wrong or outdated. Config location unknown: toml dependency is imported but config file path/format not evident in file list—may be undocumented. Windows PowerShell vs pwsh: two separate shell integration files (shellIntegration.ps1 for legacy PowerShell, handled separately in init.ts)—easy to install to wrong one.

Architecture

Concepts to learn

• Pseudo-terminal (PTY) multiplexing — inshellisense uses node-pty to fork a real shell subprocess and intercept input/output—understanding PTY architecture is essential to debug why input doesn't reach the shell or suggestions don't render correctly
• ANSI escape codes and terminal control sequences — The codebase extensively uses ansi-escapes and ansi-styles to render colored suggestions and position cursors in the terminal; modifying rendering logic requires understanding SGR codes and cursor movement escape sequences
• Shell sourcing and environment variable inheritance — init.ts injects shell integration scripts via >> ~/.bashrc style appends; these scripts source inshellisense into the user's shell environment—any changes to shell initialization must respect shell execution order and environment propagation
• xterm.js headless rendering — inshellisense uses @xterm/headless to render terminal output without a DOM—this is a non-standard xterm.js use case that requires careful buffer management and line wrapping logic
• Spec-driven code generation — @withfig/autocomplete provides JSON specs for 600+ tools; src/runtime/generator.ts must parse these specs and convert them to executable completion providers—understanding this pattern is critical for adding new completion sources or modifying spec handling
• Keybinding capture in cooked vs raw terminal mode — inshellisense captures tab/arrow/esc keys only when suggestions are visible, otherwise passes them through to the shell—this requires toggling between canonical (cooked) and non-canonical (raw) terminal modes via termios, complex on Windows
• JSON Schema validation (ajv) — The codebase includes ajv for JSON schema validation (visible in dependencies) likely for validating autocomplete spec structure—understanding how specs are validated is important for debugging completion failures

Related repos

• withfig/autocomplete — Upstream spec repository that inshellisense depends on (v2.675.0) for the 600+ CLI tool definitions—this is the source of truth for what completions are available
• microsoft/vscode — Sibling Microsoft project; both use IntelliSense branding and xterm.js for rendering, share contributor overlap and architectural inspiration
• zsh-users/zsh-autosuggestions — Alternative shell autocomplete for zsh specifically (history-based) vs inshellisense (spec-based); direct competitor in the zsh ecosystem
• scop/bash-completion — Traditional bash-completion project (systemd-managed); inshellisense modernizes this concept with IDE-style rendering and multi-shell support
• nushell/nushell — Modern shell ecosystem that inshellisense supports; users of nushell rely on inshellisense for autocomplete parity with other shells

PR ideas

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 src/runtime/parser.ts

The parser module is a critical component for parsing shell commands and generating suggestions, but currently only has snapshot tests in src/tests/runtime/snapshots/parser.test.ts.snap. A new contributor should add granular unit tests covering edge cases like malformed input, special characters, nested quotes, and command aliases. This will improve code reliability and make refactoring safer.

• [ ] Review existing snapshot tests in src/tests/runtime/snapshots/parser.test.ts.snap
• [ ] Create new test cases in src/tests/runtime/parser.test.ts covering: empty input, quoted arguments, escaped characters, pipes, redirects
• [ ] Test integration with src/runtime/alias.ts to ensure aliases are parsed correctly
• [ ] Ensure test coverage is >80% for the parser module
• [ ] Run 'npm test' to verify all tests pass

Add unit tests for src/runtime/generator.ts and src/runtime/suggestion.ts

The generator and suggestion modules handle the core logic for generating IDE-style autocomplete suggestions, but there are no dedicated test files in src/tests/runtime/ for these files. These are critical path components that would benefit significantly from thorough unit test coverage before any refactoring or feature additions.

• [ ] Create src/tests/runtime/generator.test.ts with tests for suggestion generation logic
• [ ] Create src/tests/runtime/suggestion.test.ts with tests for suggestion filtering and ranking
• [ ] Test interaction between generator.ts and the @withfig/autocomplete dependency
• [ ] Add tests for edge cases: empty completions, duplicate suggestions, special characters in suggestions
• [ ] Run 'npm test' and ensure coverage reports are generated

Add shell integration tests for untested shells in src/tests/isterm/

The repo supports multiple shells (bash, zsh, fish, PowerShell, nushell, xonsh) as evidenced by shell/* files, but src/tests/isterm/ only has pty.test.ts. There are no integration tests validating that shell integrations work correctly. A new contributor should add shell-specific integration tests using the existing shell integration files.

• [ ] Review shell integration files: shell/shellIntegration.bash, shell/shellIntegration.fish, shell/shellIntegration.ps1, shell/shellIntegration.nu
• [ ] Create src/tests/isterm/shell-integration.test.ts to test shell hook injection
• [ ] Add tests for each shell verifying: proper alias sourcing, command execution, PTY communication
• [ ] Use src/isterm/pty.ts as reference for PTY testing patterns
• [ ] Run e2e tests with 'npm run test:e2e' to ensure shell integrations function correctly

Good first issues

• Add unit tests for src/runtime/alias.ts—the alias resolution logic has no Jest test file visible in file list, but is critical for correct command completion when users have custom shell aliases.
• Document the inshellisense configuration file format and location—package.json shows a toml dependency but no config.md or config schema file exists; add docs/CONFIG.md with example TOML and location per shell.
• Create an end-to-end test for shell integration inject/remove (is init && is uninstall)—currently only has e2e tests via tui-test; add a test that verifies init.ts correctly appends/removes lines from real .bashrc/.zshrc files without corruption.

Top contributors

• @cpendery — 92 commits
• @yixiaojiu — 1 commits
• @krisbiradar — 1 commits
• @arya2004 — 1 commits
• @GeekerHWH — 1 commits

Recent commits

• 9c7f5fd — fix: don't parse command if output is detected (#403) (cpendery)
• 86bdd7b — build: bump formula version (cpendery)
• 5faa747 — build: bump to 0.0.1 (#402) (cpendery)
• 0486a19 — fix: ignored commands were still loading (#401) (cpendery)
• c663bb5 — fix: custom spec is not loaded correctly (#364) (yixiaojiu)
• 963d6ed — fix: zsh with oh-my-zsh (#400) (cpendery)
• 57b464c — feat: add max-suggestion config (#387) (krisbiradar)
• db4889f — build: fix homebrew checksum (cpendery)
• e62f42c — build: bump formula version (cpendery)
• aa4aab5 — build: bump to 0.0.1-rc.32 (#396) (cpendery)

Security observations

• High · Outdated Node PTY Dependency with Known Vulnerabilities — package.json - dependencies.node-pty. The project uses 'node-pty' version 1.2.0-beta.8, which is a beta release. Beta versions may contain unpatched security vulnerabilities and lack production-grade stability. The dependency is used for PTY (pseudo-terminal) operations, which handle shell interactions and could be exploited. Fix: Upgrade to the latest stable release of node-pty (currently 0.10.x or higher stable version). Avoid using beta versions in production code, especially for security-sensitive components like PTY handling.
• High · Potential Command Injection via Shell Integration Scripts — shell/*.sh, shell/*.bash, shell/*.zsh, shell/*.ps1, shell/*.fish, shell/*.nu, shell/*.xsh files and src/runtime/ directory. The project includes multiple shell integration scripts (bash, zsh, fish, powershell, etc.) that execute shell commands. If user input is not properly sanitized before being passed to these scripts, it could allow shell injection attacks. The runtime components (src/runtime/generator.ts, src/runtime/parser.ts) process user commands. Fix: Implement strict input validation and sanitization for all user-provided command inputs. Use parameterized/quoted command execution where possible. Audit shell integration scripts for unsafe variable expansion (avoid unquoted variables). Use shellcheck or similar linters on all shell scripts.
• Medium · Arbitrary Code Execution via Autocomplete Specifications — package.json - dependencies.@withfig/autocomplete, src/runtime/generator.ts, src/runtime/replacement.ts, src/commands/specs/. The project loads autocomplete specifications from '@withfig/autocomplete' package (v2.675.0) and processes them through the runtime. If an attacker can manipulate the specs or if specs contain malicious code, it could lead to arbitrary command execution, especially given the runtime evaluation in src/runtime/generator.ts and src/runtime/replacement.ts. Fix: Validate and sanitize all autocomplete specifications before execution. Implement a content security policy for spec execution. Consider sandboxing spec evaluation. Regularly audit the @withfig/autocomplete package for security updates. Pin to specific versions rather than using caret (^) ranges for this critical dependency.
• Medium · Potential Path Traversal via Alias Processing — src/runtime/alias.ts, src/runtime/parser.ts. The src/runtime/alias.ts module processes shell aliases. If aliases are not properly validated, an attacker could craft malicious aliases that reference arbitrary files on the system via path traversal sequences (../, etc.), potentially leading to information disclosure or unintended command execution. Fix: Implement strict validation for alias paths and commands. Use path normalization functions (e.g., path.resolve() + path.relative()) to prevent path traversal. Reject aliases containing suspicious patterns like '../', absolute paths pointing outside intended directories, or shell metacharacters.
• Medium · Unsafe PTY Configuration and Input Handling — src/isterm/pty.ts, src/isterm/commandManager.ts. The PTY implementation (src/isterm/pty.ts) manages pseudo-terminal sessions. Improper handling of PTY input/output could allow buffer overflows, injection attacks, or access to sensitive terminal data. The terminal interaction with xterm (@xterm/headless) needs careful validation. Fix: Implement strict bounds checking on all PTY input/output operations. Validate and sanitize all terminal input before processing. Use xterm's built-in security features and keep it updated. Implement rate limiting on PTY operations to prevent DoS attacks. Never expose raw PTY access to untrusted input.
• Medium · Dependency with Unspecified Version Pinning — package.json - dependencies section (multiple entries with ^ prefix). Several dependencies use caret (^) version constraints which allow minor and patch version updates automatically. For security-critical components like 'node-pty', 'commander', and 'ajv', this could introduce vulnerabilities from unexpected updates. Fix: Pin all critical security-related dependencies to exact versions using format 'X.Y.Z' instead of '^X.Y.Z'. At minimum, replace caret constraints with tilde (~) constraints for dependencies involved in command execution and parsing. Review and update dependencies regularly through controlled processes.
• Low · Missing Security Headers — undefined. undefined Fix: undefined

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

Where to read next

• 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.