aliasman

An AI-harness based alias manager for macOS — semantic search, shell history analytics, and native Claude Code integration.

Manage your zsh/bash aliases from the CLI — add, update, delete, list, and search — without ever manually editing your shell config.

---

Install • Commands • Claude Code • MCP • Requirements

---

Features

Feature	Description
Alias CRUD	Add, update, delete, and list aliases with tags and descriptions
History analytics	See your most-used commands and get alias suggestions
Semantic search	Find aliases by meaning using local embeddings (LanceDB + Ollama)
MCP server	Expose alias search to Claude and other MCP-compatible tools
Claude Code hook	Injects your aliases into Claude's session context (token-budget aware)
Safe shell injection	Writes a managed block into .zshrc/.bashrc — never corrupts the file
Alias packs	Install, share, and manage curated alias collections (k8s, docker, and more)
Atomic persistence	TOML data store with timestamped backups

---

Installation

Homebrew (recommended)

brew tap adityak74/aliasman
brew install adityak74/aliasman/aliasman

From source

cargo install --path .

Initialize

After installing, run:

aliasman init

This auto-detects your shell, imports any existing aliases, and injects a managed block into your shell config.

---

Commands

Alias management

# Add an alias
aliasman add --name gs --command "git status"
aliasman add --name k --command "kubectl" --description "k8s shorthand" --tag k8s

# Update an alias
aliasman update --name gs --command "git status --short"

# Delete an alias
aliasman delete --name gs

# List all aliases
aliasman list
aliasman list --shell zsh

Shell history

# Show command frequency stats
aliasman stats
aliasman stats --top 30 --verbose

# Suggest aliases for frequent long commands
aliasman suggest

# Apply a suggestion
aliasman suggest --apply <alias-name>

Alias packs

# Install the built-in k8s pack
aliasman pack install-builtin k8s

# Install a pack from a file or URL
aliasman pack install ./my-pack.toml
aliasman pack install https://example.com/packs/docker.toml

# List installed packs
aliasman pack list

# Remove a pack
aliasman pack remove k8s

# Create a pack from your current aliases
aliasman pack create --name my-aliases --tag work

Semantic search

Requires Ollama running locally with an embedding model.

# Search aliases by meaning
aliasman search "kubernetes port forward"
aliasman search "git undo last commit" --limit 10

# Rebuild the search index
aliasman search reindex

Claude Code integration

# Install the SessionStart hook into Claude Code settings
aliasman hook install

# Preview what the hook would inject
aliasman hook preview

# Run as hook (called automatically by Claude Code)
aliasman hook claude

The hook injects your aliases into Claude's context on session start, staying within a configurable token budget so it doesn't bloat every conversation.

MCP server

# Start the MCP stdio server (for use with Claude or other MCP clients)
aliasman mcp serve

Exposes an alias_search tool that MCP clients can call to find relevant aliases by natural language query.

---

Data files

File	Purpose
~/.config/aliasman/aliases.toml	Canonical alias store
~/.config/aliasman/packs/	Installed pack files
~/.aliases	Generated shell alias file (sourced by your shell config)

---

Star History

---

Recent Updates

v0.1.1 — aliasman hook install now preserves existing Claude Code hooks (SessionEnd, PreToolUse, etc.) instead of replacing the entire hooks object in settings.json.

Requirements

• Rust 1.75+
• Ollama (optional) — for semantic search; run ollama pull nomic-embed-text

---

Contributing

Issues and PRs are welcome. See GitHub Issues to report bugs or request features.

---

License

MIT

---

If aliasman saves you time, consider giving it a ⭐ on GitHub — it helps others find the project.