Skip to content

installation.md

Latest commit

 

History

History
477 lines (399 loc) · 24.8 KB

installation.md

File metadata and controls

477 lines (399 loc) · 24.8 KB
Raw

Installation and source-build guide

This guide defines the supported installation pathways for the ai-session-search Python distribution, Rust crate, and aise executable. Prefer a package registry for normal use. Install from Git only when testing an unreleased change or when a specific commit is required.

The canonical repository URL is https://github.com/ahundt/ai-session-search. Maintainers must keep it equal to project.urls.Repository in pyproject.toml and workspace.package.repository in Cargo.toml; installation documentation must not introduce a second repository identity.

Install in five steps

  1. Choose exactly one owner for the global aise executable: uv tool (recommended), Cargo, pip, or a verified native archive.
  2. Run one command from Registry installation, or use an immutable Git revision when testing unreleased code.
  3. Run aise --version, aise package status, and aise config paths to confirm which executable and state directories are active.
  4. Run aise integrations install and aise integrations status to create the aisearch and ai_session_search aliases, register the same executable with detected MCP clients, and install managed agent instructions. Use aise integrations install --dry-run first when targeting existing custom files.
  5. Run aise doctor to check the background index preparation started by integration installation. When it reports a usable index, run aise list and aise search "QUERY" to verify the search path end to end. Use aise reindex only when aise doctor reports that explicit recovery is required.

To update or remove the product later, follow Update and uninstall in order. Integration removal must happen before removing the executable that performs it.

Registry installation

Choose one global aise command owner. Installing both uv and Cargo/native global commands can select different builds based on PATH order. Install the standalone command in uv's isolated tool environment:

uv tool install ai-session-search
aise --help

Run it without a persistent installation:

uvx --from ai-session-search aise --help

Add the Python API to a uv-managed project:

uv add ai-session-search

Install the Python API and command with pip:

python -m pip install ai-session-search

Install the native Rust command from crates.io:

cargo install ai-session-search --locked

These package installation commands do not create aliases, register MCP servers, write managed Markdown or skills, or install client hooks. The common aise integrations install step owns aliases and integrations without copying the package-owned executable.

After any installation method, register the same aise executable with detected MCP clients:

aise integrations install
aise integrations status

After a non-dry-run integration installation commits its owned files, it starts best-effort session index preparation in a detached aise process and returns without waiting for transcript discovery or parsing. Run aise doctor to check snapshot readiness, refresh progress, or exact recovery guidance. A dry-run or an invocation with no selected integration components starts no index work. If configuration resolution or process launch prevents preparation, the valid integration files remain installed and the command prints the exact configuration path plus aise reindex and aise doctor recovery steps.

Users who want the recommended executable plus detected-client integration can run one fail-fast shell command. Package ownership and MCP configuration remain separate transactions, so a package-manager failure never edits client files:

uv tool install ai-session-search && aise integrations install
cargo install ai-session-search --locked && aise integrations install

This follows the same proven lifecycle as RTK (rtk installation followed by rtk init -g) and autorun (uv tool installation followed by autorun --install), while aise integrations install additionally provides dry-run, status, per-client selection, durable recovery, and ownership-safe uninstall.

The default stored command is the absolute path of the first aise on the installer's PATH. This prevents a desktop client or harness from selecting a shadowed installation through a different PATH order. Use --binary PATH to select another installation deliberately. Supported selectors are claude, codex, gemini, antigravity, pi, prime-agent, cursor, windsurf, vscode, zed, opencode, openclaw, and kilocode; omission or all updates detected clients. Repeat --client CLIENT to include several explicit clients, or repeat --exclude-client CLIENT to remove clients from that set. Explicit custom paths are always included and are not client aliases, so exclusions do not discard them. The Kilo selector is explicitly the legacy VS Code extension adapter. Current standalone Kilo uses ~/.config/kilo/kilo.jsonc and is not modified. The installer adds managed instruction guidance for Claude, Codex, OpenCode, Gemini, Antigravity, Pi, and Prime Agent; Gemini and Antigravity share ~/.gemini/GEMINI.md, while Pi and Prime use ~/.pi/agent/AGENTS.md and ~/.prime/agent/AGENTS.md. It does not install hooks. Pi has no built-in MCP client, and Prime currently accepts remote HTTP MCP servers rather than a local stdio subprocess, so selecting either installs its skill and guidance without writing a false MCP registration. It installs one ai-session-search skill package for detected or explicitly selected Claude, Codex, Gemini, Antigravity, Pi, and Prime Agent harnesses. The app owns the canonical package under ~/.ai-session-search/skills/, beside ~/.ai-session-search/config.toml. This app directory is a sibling of ~/.claude, not a child of it and not a harness-owned location. The ai-session-search/ package contains general harness guidance in SKILL.md, adjacent aise-capability.toml with the deterministic message-classification rules executed by aise skills corrections, and references/message-classification.md. Harness-native discovery links point to the canonical package from ~/.claude/skills/ (Claude Code CLI/Desktop), ~/.agents/skills/ (ChatGPT Codex desktop and Codex CLI/IDE), ~/.gemini/skills/ (Gemini), ~/.gemini/config/skills/ (Antigravity App/IDE), ~/.gemini/antigravity-cli/skills/ (Antigravity CLI), ~/.pi/agent/skills/ (Pi), and ~/.prime/agent/skills/ (Prime Agent). Pi and Prime also read ~/.agents/skills/, but their native links make explicit installs and lifecycle status independent of Codex detection. Pi's and Prime's own CLIs accept a repeatable --skill PATH, and their --no-skills only disables discovery, so an explicit path stays active. Selecting several harnesses keeps every selected discovery directory; shared destinations are deduplicated. Use repeatable --skill-root DIR for one or more exact additional package destinations. Each custom directory must end in ai-session-search; it names a package directory, not a file inside one.

Reinstall replaces a prerelease copied harness package with a discovery link only when the old copy is provably app-managed and untouched. A modified file, extra user file, unmanaged directory, or retargeted link is preserved and reported instead of overwritten. Uninstall removes a discovery entry only while it is still the exact link created by aise, and retains the canonical package while another supported harness still links to it. Install, aise skills update, and normal uninstall retire the earlier sibling corrections package and its discovery links only when the ownership manifest, file digests, and exact link targets still match; dry-run reports each planned removal without changing the installation. Generated guidance introduces the product as AI Session Search (aise) and walks the four-step workflow with the MCP tool for each (list_sessions for recent sessions by directory or period, search_sessions for a topic, search_messages for the exact turn, get_session to read it), names the installed skill and the CLI fallback, and the same sentence is the MCP server's initialize instructions; Pi and Prime Agent, which get no MCP registration, receive the same four steps as aise commands. Claude's imported AI_SESSION_SEARCH.md has an explicit whole-file ownership sentinel so upgrades can replace older aise-owned wording while refusing to overwrite user-owned content.

Published wheels support GIL-enabled CPython 3.12 through 3.14 on manylinux2014 x86_64/aarch64, macOS x86_64/arm64, and Windows x86_64; they do not require a local Rust compiler. Git, sdist, and Cargo installations build native code from source and require Git, Rust 1.88 or newer, and a C linker for the target platform.

Update and uninstall

Use the same owner for installation, update, and removal. Before removing a global command, remove its MCP registrations while the command is still available:

# Detect the owner, show evidence, and ask before invoking its update command.
aise package update
# Check without invoking a package manager.
aise package check

aise integrations uninstall

# Choose only the commands matching the installation owner or project use.
uv tool upgrade ai-session-search && aise integrations install
uv tool uninstall ai-session-search
uv remove ai-session-search
python -m pip uninstall ai-session-search
cargo install ai-session-search --locked && aise integrations install
cargo uninstall ai-session-search

aise package update --yes skips the confirmation prompt but still requires authoritative ownership evidence. The command delegates to uv, pip, pipx, Cargo, or Homebrew, then runs the replacement executable's conservative skills update after the manager succeeds. That command visits only roots in the install manifest, including custom roots, and never discovers or configures new clients. It never overwrites the executable itself. It refuses automatic apply for a direct URL or source checkout, including a maintainer checkout installed into a uv tool environment or with cargo install --path or cargo install --git, and for unknown executables. Update the recorded source with its original workflow instead.

Stable-release notifications are a separate read-only CLI convenience. Disable them per invocation with --skip-release-notification, by setting AI_SESSION_SEARCH_SKIP_RELEASE_NOTIFICATION=1, or persistently with:

[release_notifications]
enabled = false
minimum_check_interval_hours = 24
request_timeout_ms = 1000

Explicit aise package check and aise package update remain available when notifications are disabled. MCP stdio, noninteractive output, and Rust/Python library calls never perform notification checks.

aise integrations uninstall removes owned MCP entries, executable aliases, managed guidance, and managed skills by default while preserving the aise executable. Use --keep-mcp, --keep-aliases, --keep-instructions, or --keep-skill to retain one integration component. Neither MCP nor package-manager uninstall deletes the index, configuration, or source session files.

Integration lifecycle operations are aise integrations install, status, uninstall, and recover. The aise mcp namespace has one user-facing command, serve (aise mcp schema-budget is a hidden maintainer measurement). aise integrations install does not bypass package ownership: the running CLI must already be provided by uv, Cargo, pip, or a verified native archive. It verifies that aise is on PATH, then installs or refreshes MCP registrations and managed instructions. This prevents an ephemeral uvx, source-tree, or Python interpreter process from being copied and mislabeled as a package-managed installation.

aise integrations install is an idempotent integration refresh: rerunning the same version changes no bytes, while running it after a package-manager update refreshes owned relative aisearch -> aise and ai_session_search -> aise symbolic links, MCP entries, instruction text, and session-index freshness through the same detached preparation path used after a first install. It refuses to replace either alias path when that path is not an owned symbolic link. Use --dry-run before mutation, repeat --client CLIENT for an explicit include set, repeat --exclude-client CLIENT to subtract clients, or use --no-mcp, --no-instructions, --no-skill, or --no-aliases to omit one integration component. The custom config, Markdown, and exact --skill-root flags are shown by aise integrations install --help. Use the separate aise integrations uninstall command with the same target selectors; --keep-mcp, --keep-instructions, --keep-skill, and --keep-aliases retain the named component while removing the other selected integrations. Neither command installs or removes the package-owned aise executable.

Skill directories use an explicit ownership marker in SKILL.md, which gates the whole directory: checking each file separately would let a tree be half owned, so aise would overwrite the files it wrote and refuse the one you edited, leaving a directory matching neither version. An unmanaged file at a selected destination stops the entire preflight before MCP, instruction, or skill files are published, and the error names the conflicting path and the --skill-root alternative.

Install also writes skill-install-manifest.json beside your config, recording the path, byte count, and SHA-256 of every file it wrote. That record is what lets status distinguish an older install nobody touched from a file you changed -- byte comparison alone answers only "does this equal the current build", and a NO covers both. Skill status is therefore one of configured, outdated, untouched, modified or damaged, missing, or legacy, ownership uncertain. It never claims to know whether a change was an intentional edit or corruption, because nothing on disk carries that intent.

Uninstall removes a skill directory only when every managed file is exactly what install recorded and nothing else lives in it. Any other state preserves the WHOLE directory and reports each reason: removing an unchanged SKILL.md while leaving your edited aise-capability.toml would orphan your file behind a skill that no longer declares itself. --force-full-cleanup deletes everything under one exact --skill-root, including files you wrote; it requires that root, refuses --keep-skill, and never touches your index, cache, or configuration.

Skills participate in the same durable receipt as MCP and instruction edits, and the manifest is published by that same transaction, so it cannot survive a rollback and claim an install that never happened.

The links are relative so moving an intact bin directory keeps them valid. Unix supports them directly. Windows requires symbolic-link permission (normally Developer Mode or an elevated process); if the operating system rejects link creation, the command reports the failed path and recommends --no-aliases. The installer never substitutes copied binaries, hard links, .cmd wrappers, or extra Python console scripts because those create divergent ownership and update behavior.

For a pip-owned global installation, update and refresh with:

python -m pip install --upgrade ai-session-search && aise integrations install

For a verified native archive, run its rollback-preserving installer and then aise skills update. The installer publishes aise-native-install.json beside the executable; its archive identity and SHA-256 digest let aise package status distinguish this owner from an unknown standalone binary. Replacement still requires a newly downloaded archive whose checksums and provenance were verified, --replace, and an explicit rollback backup. If an older ownership receipt exists, its rollback copy is written at BACKUP.aise-native-install.json; restore it together with BACKUP so aise package status continues to recognize the prior archive. Do not mix uv-, Cargo-, pip-, and native-owned executables on one PATH; aise package status reports the active executable and every matching candidate when ownership is unclear.

Keep their bin directories distinct as well. In particular, do not point UV_TOOL_BIN_DIR at a Cargo installation root's bin directory or a native archive destination. Cargo refuses an existing unknown aise unless --force is explicit, but uv tool install --force can replace an existing file in its configured bin directory without identifying the previous package manager. Distinct directories preserve each manager's ownership metadata; aise package status reports every executable on PATH and warns that the first one wins.

Custom installation locations

Keep executable ownership separate from client configuration. Use the package manager's supported destination controls, then pass the resulting executable to aise integrations install only when a graphical client cannot resolve it from PATH:

# uv tool environment and executable directory
UV_TOOL_DIR=/custom/uv/tools UV_TOOL_BIN_DIR=/custom/bin \
  uv tool install ai-session-search

# Cargo installation root; the executable is /custom/cargo/bin/aise
cargo install --root /custom/cargo ai-session-search --locked

# Extracted verified native archive (the packaged script is named install.sh)
sh install.sh --bin-dir /custom/bin

# Repository checkout used by maintainers
sh scripts/install-native.sh --bin-dir /custom/bin

# Register that executable with detected clients
/custom/bin/aise integrations install --binary /custom/bin/aise

Use the same uv environment variables or Cargo --root when upgrading or uninstalling so the package manager edits the installation it owns. Integration removal remains /custom/bin/aise integrations uninstall and must run before executable removal. aise integrations install --help exposes typed paths for common JSON, VS Code, Zed, OpenCode, Codex TOML, Claude Markdown, Gemini/Antigravity Markdown, AGENTS.md, and recovery receipt locations; those flags configure integrations, not package ownership.

The integration acceptance matrix covers Claude Code/Desktop, ChatGPT Codex desktop and Codex CLI/IDE, Gemini CLI, Antigravity App/IDE/CLI, Pi, Prime Agent, Cursor, Windsurf, VS Code, Zed, OpenCode, OpenClaw, and the legacy KiloCode adapter. Pi and Prime Agent acceptance covers native skill discovery, managed AGENTS.md, explicit selection, status, idempotent reinstall, dry-run, and ownership-safe uninstall; it intentionally expects no local stdio MCP target. Antigravity App/IDE and CLI share the current ~/.gemini/config/mcp_config.json; the installer also maintains the two legacy Antigravity MCP locations for older harness versions. App/IDE and CLI use distinct current skill roots while sharing managed ~/.gemini/GEMINI.md instructions with Gemini. OpenCode uses mcp.ai-session-search in ~/.config/opencode/opencode.json and a managed block in ~/.config/opencode/AGENTS.md. Each target must pass install, content-aware status, byte-idempotent reinstall, dry-run, and ownership-safe uninstall tests.

Managed client configurations and MCP initialization use the descriptive ai-session-search server identity and the human-readable title AI Session Search, while the single executable remains aise. Reinstall atomically replaces the historical ai_session_search and aise registration keys so clients do not load duplicate servers; uninstall recognizes and removes all three owned keys during migration.

Install an immutable Git revision

Use a full commit object ID rather than main, another branch, a tag, or an abbreviated hash. A full hash makes the selected source unambiguous and lets pip avoid extra network work. Replace the example revision below with the commit to test:

REPOSITORY_URL=https://github.com/ahundt/ai-session-search
REV=0123456789abcdef0123456789abcdef01234567

Install the standalone command with uv:

uv tool install "ai-session-search @ git+$REPOSITORY_URL@$REV"

Run the command ephemerally:

uvx --from "ai-session-search @ git+$REPOSITORY_URL@$REV" aise --help

Add the pinned source to a uv project:

uv add "ai-session-search @ git+$REPOSITORY_URL@$REV"

Install the Python API and command with pip:

python -m pip install "ai-session-search @ git+$REPOSITORY_URL@$REV"

Install the native Rust command:

cargo install ai-session-search \
  --git "$REPOSITORY_URL" \
  --rev "$REV" \
  --locked

Maintainer acceptance contract

CI checks direct-Git installation without depending on GitHub availability. It uses the checked-out repository as a file:// remote and $GITHUB_SHA as the immutable revision, then verifies pip, uv add, uv tool install, uvx, and cargo install --git. The Python acceptance harness is reusable locally:

uv run --isolated --no-project python scripts/verify_python_install_methods.py \
  --git-url "file://$(git rev-parse --show-toplevel)" \
  --git-rev "$(git rev-parse HEAD)" \
  --source-root "$(git rev-parse --show-toplevel)" \
  --timeout-seconds 600

The harness deliberately accepts the repository and revision as parameters. It rejects mutable or abbreviated revisions, insecure HTTP, embedded credentials, and relative local paths. Temporary virtual environments, tool installations, configuration, and application caches are scoped to one temporary root and removed on success or failure. The harness deliberately inherits the caller's content-addressed uv cache and CARGO_TARGET_DIR: normal standalone invocations reuse uv's platform cache, while run_ci_local.sh selects the workspace target directory. Set either environment variable explicitly to use a different shared cache; the harness never deletes it.

run_ci_local.sh defaults CARGO_INCREMENTAL=0 because its full build/test/package gate does not benefit from retaining a second multi-gigabyte incremental graph. It preserves an explicit caller value and an inherited RUSTC_WRAPPER such as sccache; set AI_SESSION_SEARCH_RUSTC_WRAPPER= to disable that wrapper for one gate. If Cargo reports No space left on device, inspect target first. Remove only workspace-owned output with cargo clean or a more selective cargo clean -p <package> after confirming no other build is using it. Do not delete $CARGO_HOME or uv's shared cache as an automatic recovery step.

Primary references

When these tools change syntax or security guidance, update this guide, the CI workflow, and the installer acceptance tests in the same commit.