claude-code-tools 1.0.10__py3-none-any.whl

claude_code_tools-1.0.10.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

claude_code_tools-1.0.10.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+aichat = claude_code_tools.aichat:main
+env-safe = claude_code_tools.env_safe:main
+tmux-cli = claude_code_tools.tmux_cli_controller:main
+vault = claude_code_tools.dotenv_vault:main

claude_code_tools-1.0.10.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Prasad Chalasani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/cc-codex-instructions.md

@@ -0,0 +1,37 @@
+# Codex MCP Tool Usage in Claude Code
+
+## Required Parameters
+
+When using the `mcp__gpt-codex__codex` tool in Claude Code, always include these parameters to ensure proper functionality:
+
+```json
+{
+  "prompt": "your prompt here",
+  "sandbox": "workspace-write",
+  "approval-policy": "never",
+  "include-plan-tool": false
+}
+```
+
+## Parameter Explanation
+
+- **`sandbox`**: Set to `"workspace-write"` to allow file modifications in the project
+- **`approval-policy`**: Set to `"never"` to avoid approval prompts that block execution
+- **`include-plan-tool`**: Set to `false` for Claude Code compatibility (prevents response format issues)
+
+## Example Usage
+
+```python
+mcp__gpt-codex__codex(
+    prompt="Analyze this codebase and suggest optimizations",
+    sandbox="workspace-write",
+    approval-policy="never",
+    include-plan-tool=false
+)
+```
+
+## Notes
+
+- These overrides are necessary when `include_plan_tool = true` in the global config
+- Without `include-plan-tool: false`, responses may not display properly in Claude Code
+- The `approval-policy: "never"` prevents the tool from waiting for user approval

docs/claude-code-chutes.md

@@ -0,0 +1,138 @@
+Here’s what I found (forums + docs) and the cleanest ways to run **Claude Code** against **Chutes (OpenAI-compatible) instead of Anthropic models**—including whether you need an extra router.
+
+---
+
+## TL;DR
+
+* **You can’t point Claude Code directly at Chutes** because Claude Code speaks the **Anthropic `/v1/messages`** format, while Chutes exposes an **OpenAI-compatible `/v1/chat/completions`** API. You need a **translator/gateway** in the middle. ([Anthropic][1])
+* Two working choices seen in the community and in Anthropic’s docs:
+
+  1. **Claude Code Router (CCR)** — purpose-built local proxy that converts Claude Code → OpenAI format; works with OpenRouter, DeepSeek, Groq, etc., and also with custom OpenAI-compatible bases like **Chutes**. ([GitHub][2], [npm][3])
+  2. **LiteLLM “Anthropic unified endpoint”** — run LiteLLM as a gateway that **exposes an Anthropic-style endpoint** to Claude Code, while LiteLLM calls Chutes behind the scenes using its **OpenAI-compatible** route. ([Anthropic][1], [LiteLLM][4], [LiteLLM][5])
+
+Reddit users repeatedly report running **Claude Code + Chutes** successfully (often with GLM-4.5, DeepSeek, or Kimi K2) by using a router/gateway. ([Reddit][6], [Reddit][7], [Reddit][8])
+
+---
+
+## Option A — Claude Code Router (simplest)
+
+**When to choose:** quick setup focused on Claude Code; easy model switching with `/model`.
+
+1. **Install**
+
+```bash
+npm i -g @anthropic-ai/claude-code @musistudio/claude-code-router
+```
+
+CCR runs a local server and translates requests for you. ([GitHub][2])
+
+2. **Configure CCR for Chutes**
+   Create `~/.claude-code-router/config.json` like:
+
+```json
+{
+  "Providers": [
+    {
+      "name": "chutes",
+      "api_base_url": "https://llm.chutes.ai/v1/chat/completions",
+      "api_keys": ["YOUR_CHUTES_API_KEY"],
+      "models": ["deepseek-ai/DeepSeek-V3-0324"],
+      "transformer": { "use": ["openrouter"] }
+    }
+  ],
+  "Router": { "default": "chutes,deepseek-ai/DeepSeek-V3-0324" }
+}
+```
+
+Notes:
+
+* Chutes’ **base URL** is OpenAI-style: `https://llm.chutes.ai/v1/chat/completions`. ([Reddit][9])
+* Model IDs vary (e.g., `deepseek-ai/DeepSeek-V3-0324`, `Qwen/Qwen3-235B-A22B`, `ZhipuAI/glm-4.5`)—grab the exact string from Chutes’ model page. ([Reddit][9])
+
+3. **Start CCR and point Claude Code at it**
+
+```bash
+ccr start
+export ANTHROPIC_BASE_URL=http://127.0.0.1:3456
+claude
+```
+
+CCR exposes an Anthropic-compatible endpoint; setting `ANTHROPIC_BASE_URL` makes Claude Code use it. In the Claude Code REPL you can switch models with `/model provider,model`. ([npm][3])
+
+**Community confirmation:** multiple Reddit threads mention using Claude Code with GLM-4.5/DeepSeek **via Chutes** (often preferring CCR). ([Reddit][6], [Reddit][7])
+**Video walkthroughs:** several YouTube explainers demo **Claude Code Router**, setup, and model routing. ([YouTube][10], [YouTube][11])
+
+---
+
+## Option B — LiteLLM “Anthropic unified endpoint” (more general)
+
+**When to choose:** you want observability, spend controls, or to route many providers with one gateway.
+
+1. **Define a LiteLLM model that points to Chutes**
+   Create `litellm_config.yaml`:
+
+```yaml
+model_list:
+  - model_name: chutes-deepseek-v3
+    litellm_params:
+      model: openai/deepseek-ai/DeepSeek-V3-0324   # tell LiteLLM it's OpenAI-compatible
+      api_base: https://llm.chutes.ai/v1           # base should include /v1
+      api_key: YOUR_CHUTES_API_KEY
+```
+
+LiteLLM’s OpenAI-compatible docs show the `openai/` prefix and the need for `/v1` in `api_base`. ([LiteLLM][5])
+
+2. **Run LiteLLM and expose an Anthropic-style endpoint**
+
+```bash
+litellm --config /path/to/litellm_config.yaml
+export ANTHROPIC_BASE_URL=http://127.0.0.1:4000
+claude
+```
+
+Anthropic’s **LLM Gateway** guide explicitly supports setting `ANTHROPIC_BASE_URL` to a LiteLLM endpoint that speaks the **Anthropic messages** format. ([Anthropic][1], [LiteLLM][4])
+
+**Working example calling Chutes through LiteLLM (code snippet/gist):** shows `api_base="https://llm.chutes.ai/v1"` and an `openai/...` model. ([Gist][12])
+
+---
+
+## Do you need “Claude Code Router”?
+
+* **You need some router/gateway.** Claude Code won’t talk directly to Chutes’ OpenAI endpoint. You can use **CCR** (purpose-built) **or** **LiteLLM** (general gateway). Anthropic’s own docs describe the LiteLLM route with `ANTHROPIC_BASE_URL`, which is often the most “officially documented” path. ([Anthropic][1])
+* If you already run LiteLLM for other projects, use **Option B**. If you just want the fastest path specifically for Claude Code, **Option A (CCR)** is very popular on Reddit/YouTube. ([Reddit][7], [YouTube][10])
+
+---
+
+## Model tips & quirks from forums
+
+* **GLM-4.5** and **DeepSeek** models are frequently called out as working well with Claude Code via Chutes (router required). ([Reddit][6])
+* Some users report **tool-call robustness varies by model** (e.g., mixed results for Qwen Coder vs GLM-4.5). Test your target model for tool use. ([Reddit][13])
+* Chutes availability/rate-limit errors happen occasionally; regenerating keys or retrial often resolves. Base URL must be exact. ([Reddit][9])
+
+---
+
+### Sources
+
+* Anthropic docs — **LLM Gateway configuration** (LiteLLM, `ANTHROPIC_BASE_URL`, Anthropic-format endpoint). ([Anthropic][1])
+* LiteLLM docs — **Anthropic unified endpoint** and **OpenAI-compatible** config (`openai/` model prefix, `/v1` base). ([LiteLLM][4], [LiteLLM][5])
+* **Claude Code Router** repo/features and usage, plus fork with added key rotation & commands. ([GitHub][2], [npm][3])
+* Reddit confirmations & how-tos (Chutes base URL, examples, and user reports running Claude Code + Chutes): ([Reddit][9], [Reddit][6], [Reddit][7])
+* YouTube demos of **Claude Code Router** setup/routing. ([YouTube][10], [YouTube][11])
+
+---
+
+If you’d like, tell me your target model on Chutes (e.g., DeepSeek V3, GLM-4.5, Kimi K2), and I’ll hand you an exact `config.json` (CCR) or `litellm_config.yaml` that you can paste in and run.
+
+[1]: https://docs.anthropic.com/en/docs/claude-code/llm-gateway "LLM gateway configuration - Anthropic"
+[2]: https://github.com/musistudio/claude-code-router "GitHub - musistudio/claude-code-router: Use Claude Code as the foundation for coding infrastructure, allowing you to decide how to interact with the model while enjoying updates from Anthropic."
+[3]: https://www.npmjs.com/package/%40tellerlin/claude-code-router?activeTab=code "@tellerlin/claude-code-router - npm"
+[4]: https://docs.litellm.ai/docs/anthropic_unified?utm_source=chatgpt.com "v1/messages"
+[5]: https://docs.litellm.ai/docs/providers/openai_compatible?utm_source=chatgpt.com "OpenAI-Compatible Endpoints"
+[6]: https://www.reddit.com/r/ChatGPTCoding/comments/1mcgm9s/psa_zaiglm45_is_absolutely_crushing_it_for_coding/?utm_source=chatgpt.com "zai/glm-4.5 is absolutely crushing it for coding - way better ..."
+[7]: https://www.reddit.com/r/LocalLLaMA/comments/1mchsyd/tutorial_use_glm_45_or_any_llm_with_claude_code/?utm_source=chatgpt.com "[tutorial] Use GLM 4.5 (or any LLM) with Claude Code"
+[8]: https://www.reddit.com/r/ClaudeAI/comments/1m3nyrn/who_is_using_claude_code_with_kimi_k2_thoughts/?utm_source=chatgpt.com "Who is using Claude Code with kimi k2? Thoughts? Tips?"
+[9]: https://www.reddit.com/r/JanitorAI_Official/comments/1ju5vih/visual_guide_for_deepseek_users_via_chutesai_full/ "Visual Guide for DeepSeek Users (via Chutes.ai) – Full Credit to u/r3dux1337! : r/JanitorAI_Official"
+[10]: https://www.youtube.com/watch?pp=0gcJCfwAo7VqN5tD&v=sAuCUAZnXAE&utm_source=chatgpt.com "Claude Code Router + Gemini 2.5 Pro FREE API: RIP Gemini ..."
+[11]: https://www.youtube.com/watch?v=df-Fu2n7SLM&utm_source=chatgpt.com "The Claude Code HACK Anthropic Does Not Want You To Use"
+[12]: https://gist.github.com/aquan9/58f4a77414a74703157bf79ea1bf009f?utm_source=chatgpt.com "Using litellm with chutes.ai from the bit-tensor chutes subnet."
+[13]: https://www.reddit.com/r/LocalLLaMA/comments/1mf8la7/qwen3coder_is_bad_at_tool_call_while_glm45_is/?utm_source=chatgpt.com "Qwen3-Coder is bad at tool call while glm-4.5 is ..."

docs/claude-code-tmux-tutorials.md

@@ -0,0 +1,105 @@
+# Advanced tmux + Claude Code Integration Resources
+
+Based on comprehensive research across multiple platforms, here's a curated collection of resources specifically addressing advanced tmux techniques and integration strategies with Claude Code. The findings reveal a sophisticated ecosystem with tools, workflows, and configuration strategies that go well beyond basic usage.
+
+## Essential Written Resources
+
+### Official Documentation and Team Insights
+
+**Claude Code Best Practices - Anthropic** (2024-2025)  
+https://www.anthropic.com/engineering/claude-code-best-practices  
+The official best practices document explicitly covers tmux integration for managing multiple Claude Code sessions. Key insights include workflow patterns for composing Claude Code into broader workflows with tmux for window and session management.
+
+**Latent Space Podcast - Claude Code Team Interview** (2024)  
+https://www.latent.space/p/claude-code  
+Direct insights from Boris Cherny and Cat Wu (Claude Code creators) discussing how "a lot of people use code with tmux to manage a bunch of windows and sessions happening in parallel." They emphasize the Unix utility philosophy and intentional design decisions around tmux compatibility.
+
+### Advanced Technical Tutorials
+
+**"Vibe Coding Anytime, Anywhere with tmux, Tailscale, and Claude Code"** by Nuttakit Kundum (July 2025)  
+https://nuttakitkundum.medium.com/vibe-coding-anytime-anywhere-with-tmux-tailscale-and-claude-code-fda01f3c5cd2  
+Demonstrates sophisticated session persistence workflows, showing how to maintain Claude Code sessions across devices using tmux. Covers mobile development with Galaxy Fold, SSH workflows, and tmux pane management for remote coding.
+
+**"LLM Codegen go Brrr – Parallelization with Git Worktrees and Tmux"** - DEV Community (2024)  
+https://dev.to/skeptrune/llm-codegen-go-brrr-parallelization-with-git-worktrees-and-tmux-2gop  
+Comprehensive guide on advanced parallelization techniques using Git worktrees and tmux to manage multiple Claude Code instances simultaneously. Includes pain points, manual workflows, and proposed automation solutions.
+
+**"How to automate development journaling with Claude Code"** by Takuya/Devas (June 2025)  
+https://www.devas.life/how-to-automate-development-journaling-with-claude-code/  
+In-depth integration guide combining Claude Code with tmux and neovim, including MCP integration and automated workflows. Shows building a RAG system with sophisticated tmux configurations.
+
+### Japanese Advanced Resources (Zenn Platform)
+
+The Japanese developer community has produced particularly sophisticated tmux + Claude Code resources:
+
+**"Claude Codeを並列組織化してClaude Code 'Company'にするtmuxコマンド集"** by Kazuph  
+https://zenn.dev/kazuph/articles/beb87d102bd4f5  
+Advanced tmux command collection for organizing multiple Claude Code instances into a "company" structure with boss-worker relationships using tmux panes. Includes orchestration commands and multi-agent coordination patterns.
+
+**"Claude Code Maxで実現する完全自動並列開発システム"** by Studio Prairie  
+https://zenn.dev/studio_prairie/articles/90f5fc48a6dea7  
+Demonstrates a fully automated parallel development system using Claude Code Max with tmux orchestration, showing advanced workflow automation techniques.
+
+## Video Resources
+
+While video content is limited, these stand out for advanced techniques:
+
+**"Claude Code / OpenCode + T-Mux + Worktrees: This SELF-SPAWNING AI Coder TEAM is INSANITY!"**  
+https://www.youtube.com/watch?v=bWKHPelgNgs  
+11-minute demonstration of combining Claude Code with tmux and Git Worktrees to create a self-spawning AI coder team. Covers task claiming systems, agent-spawn workflow automation, and monitoring multiple AI agents in tmux sessions.
+
+**"【AI組織実現‼️Claude Code Organization】現役エンジニアが「5人のAIが勝手に開発する会社」の作り方を解説！"**  
+https://www.youtube.com/watch?v=Qxus36eijkM  
+Japanese tutorial demonstrating advanced AI organization with hierarchical agent structures (President → Manager → Worker) using tmux session management and mouse operation configuration.
+
+## Production-Ready Tools and GitHub Projects
+
+### Claude Squad - Complete Multi-Agent Management
+https://github.com/smtg-ai/claude-squad  
+The most mature solution for managing multiple Claude Code agents. Uses tmux for isolated terminal sessions with git worktrees for separate codebases. Features include TUI interface, auto-accept mode for background tasks, and support for multiple AI agents (Claude Code, Aider, Codex).
+
+### tmux-mcp - Model Context Protocol Server
+https://github.com/nickgnd/tmux-mcp  
+Enables Claude Desktop to interact programmatically with tmux sessions. Features include listing/searching tmux sessions, viewing and navigating windows/panes, executing commands, and creating new sessions. Essential for deep tmux integration.
+
+### Advanced Configuration Scripts
+
+**Task Master Agent Spawner**  
+https://gist.github.com/worksfornow/df0cb6c4f6fd4966cd17133bc711fd20  
+Sophisticated Claude Code slash command for parallel task delegation. Creates multiple worktrees and launches Claude agents in tmux sessions with automated status tracking and branch management.
+
+## Key Integration Patterns and Workflows
+
+### Multi-Agent Parallelization Pattern
+- Use git worktrees + tmux sessions for parallel agent execution
+- Each agent gets an isolated directory and tmux session
+- Example command: `tmux new-session -d -s "agent-<task_id>" -c "worktrees/<feature_name>" claude`
+
+### Terminal Orchestration Pattern
+Brian P. Hogan's recommendation: "Use tmux. Have a pane with Claude Code and use tmux with a big scrollback buffer. Then have another pane where you run Git commands and other shell commands."
+
+### Session Persistence Pattern
+- Implement persistent tmux sessions for Claude Code context preservation
+- Tools like "claunch" provide project-specific session management
+- Critical for maintaining context across disconnections
+
+### MCP Integration Pattern
+- Use Model Context Protocol servers for programmatic tmux control
+- tmux-mcp server enables Claude Desktop to read and control tmux sessions
+- Allows AI assistants to observe and interact with terminal sessions
+
+## Advanced Techniques Summary
+
+The resources reveal several sophisticated techniques:
+
+1. **Hierarchical Agent Organization**: Using tmux panes to create boss-worker relationships between multiple Claude Code instances
+2. **Automated Worktree Management**: Scripts that automatically create git worktrees and spawn Claude Code instances in dedicated tmux sessions
+3. **Session Orchestration**: Tools for managing dozens of parallel Claude Code sessions with monitoring and merging capabilities
+4. **Mobile Development Workflows**: Using tmux for persistent remote Claude Code sessions accessible from mobile devices
+5. **Custom Slash Commands**: Creating project-specific delegation commands that leverage tmux for task distribution
+
+## Notable Gaps
+
+The research reveals that while basic tmux + Claude Code integration is well-documented, there's still room for more comprehensive English-language video tutorials covering complex tmux layout management, detailed multiplexing features, and live coding sessions with sophisticated setups.
+
+These resources represent the cutting edge of tmux + Claude Code integration, focusing on advanced techniques that leverage tmux's multiplexing capabilities to enhance Claude Code workflows significantly beyond basic usage.

docs/dot-zshrc.md

@@ -0,0 +1,307 @@
+# Zsh Shell Setup Guide
+
+This guide covers the essential setup for a productive Zsh environment with
+Oh My Zsh, plugins, and Starship prompt.
+
+## Prerequisites
+
+1. **Install Homebrew** (macOS package manager)
+   ```bash
+   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+   ```
+
+2. **Install Zsh** (usually pre-installed on macOS)
+   ```bash
+   brew install zsh
+   ```
+
+## Oh My Zsh Installation
+
+Install Oh My Zsh framework for managing Zsh configuration:
+
+```bash
+sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
+```
+
+This creates `~/.oh-my-zsh` directory and a basic `~/.zshrc` file.
+
+## Essential Plugins
+
+### 1. Zsh Autosuggestions
+
+Suggests commands as you type based on history and completions:
+
+```bash
+git clone https://github.com/zsh-users/zsh-autosuggestions ~/.zsh/zsh-autosuggestions
+```
+
+### 2. Zsh Syntax Highlighting
+
+Provides syntax highlighting for the shell:
+
+```bash
+git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting
+```
+
+### 3. Configure Plugins in .zshrc
+
+Add to your `~/.zshrc`:
+
+```bash
+# Oh My Zsh path
+export ZSH="$HOME/.oh-my-zsh"
+
+# Plugins configuration
+plugins=(
+    git
+    zsh-autosuggestions
+    zsh-syntax-highlighting
+)
+
+# Source Oh My Zsh (commented out if using Starship)
+# source $ZSH/oh-my-zsh.sh
+
+# Source autosuggestions manually if needed
+source ~/.zsh/zsh-autosuggestions/zsh-autosuggestions.zsh
+```
+
+## Starship Prompt
+
+Starship is a minimal, blazing-fast, and customizable prompt for any shell.
+
+### Installation
+
+```bash
+curl -sS https://starship.rs/install.sh | sh
+```
+
+### Configuration
+
+Add to the end of your `~/.zshrc`:
+
+```bash
+eval "$(starship init zsh)"
+```
+
+### Starship Configuration File
+
+You can customize starship by creating/editing `~/.config/starship.toml`.
+
+I recommend this `catppuccin` preset:
+
+```bash
+starship preset catppuccin-powerline -o ~/.config/starship.toml
+```
+
+But if you want to tweak it, see the starship config docs.
+https://starship.rs/guide/
+
+## Enhanced Directory Listings with eza
+
+Eza is a modern replacement for `ls` with colors, icons, and Git integration.
+
+### Installation
+
+```bash
+brew install eza
+```
+
+### Configuration
+
+Add these aliases to your `~/.zshrc` to replace default `ls` commands:
+
+```bash
+# Replace ls with eza for beautiful directory listings
+alias ls='eza --icons --group-directories-first'
+alias ll='eza -l --icons --group-directories-first --header'
+alias la='eza -la --icons --group-directories-first --header'
+alias lt='eza --tree --icons --level=2'
+alias ltd='eza --tree --icons --level=2 --only-dirs'
+
+# Extended eza aliases
+alias l='eza -lbF --git --icons'                # list with git status
+alias llm='eza -lbGd --git --sort=modified'     # long list, modified date sort
+alias lls='eza -lbhHigmuSa --time-style=long-iso --git --color-scale'  # full details
+```
+
+### Features
+
+- **Icons**: Shows file type icons (requires a Nerd Font)
+- **Colors**: Color-codes files by type and permissions
+- **Git Integration**: Shows git status in listings
+- **Tree View**: Built-in tree view with `--tree` flag
+- **Sorting**: Groups directories first by default
+
+### Usage Examples
+
+```bash
+ls              # Basic listing with icons
+ll              # Long format with details
+la              # Show hidden files
+lt              # Tree view (2 levels)
+l               # List with git status indicators
+```
+
+## Terminal Title Management
+
+Add custom terminal title that shows current directory:
+
+```bash
+# Disable auto-setting terminal title
+DISABLE_AUTO_TITLE="true"
+
+# Set terminal title to current directory
+function precmd () {
+  echo -ne "\033]0;$(print -rD $PWD)\007"
+}
+precmd
+
+# Show command being executed in title with rocket emojis
+function preexec () {
+  print -Pn "\e]0;🚀 $(print -rD $PWD) $1 🚀\a"
+}
+```
+
+## History Search Enhancement
+
+### Option 1: Atuin (Modern Shell History)
+
+Install Atuin for enhanced history search:
+
+```bash
+brew install atuin
+```
+
+Configure in `~/.zshrc`:
+
+```bash
+export ATUIN_NOBIND="true"
+eval "$(atuin init zsh)"
+# Bind to up arrow keys (depends on terminal)
+bindkey '^[[A' _atuin_search_widget
+bindkey '^[OA' _atuin_search_widget
+```
+
+### Option 2: HSTR (Simple History Search)
+
+```bash
+brew install hstr
+```
+
+Configure in `~/.zshrc`:
+
+```bash
+alias hh=hstr
+setopt histignorespace           # skip cmds w/ leading space from history
+export HSTR_CONFIG=hicolor       # get more colors
+bindkey -s "\C-r" "\C-a hstr -- \C-j"  # bind hstr to Ctrl-r
+```
+
+## Useful Aliases
+
+Add these productivity aliases to your `~/.zshrc`:
+
+```bash
+# Git aliases
+alias gsuno="git status -uno"        # git status without untracked files
+alias gspu="git stash push -m"       # stash with message
+alias gspop="git stash pop"          # pop stash
+alias gsl="git stash list"           # list stashes
+
+# Quick git commit amend and push
+function gcpq() {
+  ga -u
+  git commit --amend --no-edit
+  git push origin main --force-with-lease
+}
+
+# Tmux aliases
+alias tmnew="tmux new -s "
+alias tmls="tmux ls"
+alias tma="tmux a -t "
+alias tmk="tmux kill-session -t "
+alias tmd="tmux detach"
+```
+
+## Completion System
+
+Enable advanced tab completion:
+
+```bash
+autoload -Uz compinit
+zstyle ':completion:*' menu select
+fpath+=~/.zfunc
+```
+
+## Environment Variables
+
+Set common environment variables:
+
+```bash
+export EDITOR="nano"  # or "vim", "code", etc.
+export TERM=xterm-256color
+```
+
+## Final .zshrc Structure
+
+Your `~/.zshrc` should follow this general structure:
+
+```bash
+# 1. Oh My Zsh configuration
+export ZSH="$HOME/.oh-my-zsh"
+plugins=(git zsh-autosuggestions zsh-syntax-highlighting)
+
+# 2. Source additional files
+source ~/.zsh/zsh-autosuggestions/zsh-autosuggestions.zsh
+
+# 3. Environment variables
+export EDITOR="nano"
+export TERM=xterm-256color
+
+# 4. Aliases and functions
+alias gsuno="git status -uno"
+# ... more aliases
+
+# 5. Terminal title customization
+DISABLE_AUTO_TITLE="true"
+function precmd () { ... }
+function preexec () { ... }
+
+# 6. History search tool (Atuin or HSTR)
+eval "$(atuin init zsh)"
+
+# 7. Completion system
+autoload -Uz compinit
+zstyle ':completion:*' menu select
+
+# 8. Starship prompt (at the very end)
+eval "$(starship init zsh)"
+```
+
+## Verification
+
+After setup, verify everything works:
+
+```bash
+# Reload shell configuration
+source ~/.zshrc
+
+# Test autosuggestions (type a partial command and see suggestions)
+# Test syntax highlighting (commands should be colored)
+# Test Starship prompt (should see a styled prompt)
+```
+
+## Troubleshooting
+
+1. **Slow shell startup**: Comment out unused plugins and features
+2. **Autosuggestions not working**: Ensure the plugin is properly cloned and
+   sourced
+3. **Starship not showing**: Make sure it's the last line in `.zshrc`
+4. **Terminal title not updating**: Check if `DISABLE_AUTO_TITLE="true"` is set
+
+## Additional Resources
+
+- [Oh My Zsh Documentation](https://github.com/ohmyzsh/ohmyzsh/wiki)
+- [Starship Documentation](https://starship.rs/config/)
+- [Zsh Autosuggestions](https://github.com/zsh-users/zsh-autosuggestions)
+- [Atuin Documentation](https://github.com/atuinsh/atuin)