@culur/bash

A collection of interactive Bash utilities and custom Git subcommands designed to supercharge your Git workflow.

🚀 Prerequisites

These utilities rely on the following CLI dependencies:

• Git
• Bash (>= 4.0): Required for features like the mapfile (or readarray) command. Note that the default pre-installed Bash on macOS is version 3.2.x, which is too old and does not support mapfile.
• gum (for interactive selection prompts)
• tmux & Python 3 (required for agy-usage headless terminal screen capture and parsing)

To install these dependencies (on macOS via Homebrew):

# Install modern Bash (which includes mapfile support)
brew install bash

# Install gum, tmux, and python3
brew install gum tmux python3

---

✨ Features & Usage

This package provides interactive commands for Git workflow automation:

1. git fixup (or git-fixup)

Stage changes for a file, commit them as a fixup! commit against a target commit, and automatically execute an interactive rebase with autosquash and autostash.

• Options:

  • git fixup [NUMBER]: Search the last NUMBER commits from the entire history (by default, shows the last 10 commits related to the selected files).
  • -h, --help: Show help message.

• How it works:

  1. Checks if any staged files exist in the repository. If staged files are found, they are automatically selected. Otherwise, prompts you to interactively choose from modified/untracked files.
  2. Displays a list of commits to choose as the target.
     • By default, shows the last 10 commits related to the selected files.
     • If a positional NUMBER argument (e.g. 15) is provided, shows the last NUMBER commits from the entire history.
  3. Stages the selected file(s) (if unstaged) and commits them with fixup! <target commit subject>.
  4. Backs up the pre-rewrite state to a temporary backup branch fixup-backup/... to keep your history safe.
  5. Rebases and autosquashes automatically using git rebase -i --autosquash --autostash without opening your editor.
  6. Prompts you to delete the temporary backup branch.

• Examples:

  # Fix up staged files (or interactively choose modified files if none staged)
  git fixup
  
  # Search from the last 15 commits in the entire history
  git fixup 15

2. git out (or git-out)

Interactively pull files out of a selected commit in your history, rewriting the commit history to exclude them and returning the pulled files to your working tree as modifications.

• Options:

  • git out [COMMIT] or git out [NUMBER]: Specify the target commit directly via positional argument (e.g., HEAD~1, ~1, feat/abc, a1b2c3d) or specify an interactive limit (e.g., 5, 20). If omitted, defaults to interactively selecting from the last 50 commits.
  • -h, --help: Show help message.
  • -a, --all, --acc, --accumulation: Find all files changed from the selected commit up to HEAD (accumulate changes across subsequent commits).

• How it works:

  1. Identifies files changed in the selected commit (or up to HEAD if -a is used).
  2. Displays an interactive list allowing you to select (or multi-select) files using gum.
  3. Automatically performs an interactive rebase to check out the parent state of the target commit for those selected files (effectively removing them from the commit).
  4. Resolves conflicts cleanly, deletes files if they didn't exist in the parent commit, and handles empty commits gracefully.
  5. Restores the selected files to your working tree as staged modifications.

• Examples:

  # Interactively select a commit from the last 50 commits (Default)
  git out
  
  # Interactively select a commit from the last 5 commits
  git out 5
  
  # Pull files out of the commit HEAD~1 using shorthand ~1
  git out ~1
  
  # Pull files out of commit HEAD~2
  git out HEAD~2
  
  # Pull files out of commit at branch feat/abc
  git out feat/abc
  
  # Pull files out of commit hash a1b2c3d
  git out a1b2c3d
  
  # Pull files out of ~1 and all subsequent commits up to HEAD
  git out ~1 -a

3. git move (or git-move)

Interactively select one or multiple commits from history, preview their accumulated file changes, and move them to be placed directly after a chosen target commit using automated rebase.

• Options:

  • git move [NUMBER]: Specify the number of recent commits to display in the interactive menu (default: 50).
  • -h, --help: Show help message.

• How it works:

  1. Checks for staged, unstaged, or untracked changes, creates a working tree integrity snapshot, and stashes uncommitted work to keep the repository clean during rebase.
  2. Displays an interactive menu using gum allowing you to multi-select $n$ commits to move.
  3. Displays a summary of total accumulated file changes across only the selected commits.
  4. Prompts you to pick a single target commit (from the recent commits minus the selected ones) to insert the moved commits after.
  5. Executes git rebase -i automatically to reorder the commits in history.
     • If conflicts occur, aborts the rebase immediately and restores your initial working tree and file states cleanly.
     • Performs an integrity check on final file states against the pre-rebase snapshot, automatically rolling back and notifying you if any deviation is detected.

• Examples:

  # Interactively select commit(s) from the last 50 commits to move (Default)
  git move
  
  # Interactively select commit(s) from the last 15 commits to move
  git move 15

4. git init-config (or git-init-config)

Interactively generate and initialize .gitattributes and .gitignore files for your project by fetching official templates from GitHub repositories.

• Options:

  • -h, --help: Show help message.

• How it works:

  1. Checks if .gitattributes exists in the current project repository and prompts for confirmation to overwrite if present.
  2. Fetches the complete list of .gitattributes templates from gitattributes/gitattributes.
  3. Prompts you to search and select one or multiple languages/environments using gum.
  4. Downloads and appends the selected templates with clear block headers (#! ----- <Language> ----- !#) and GitHub source URLs, ending with a professional Custom section.
  5. Repeats the same interactive generation flow for .gitignore templates from github/gitignore.

• Examples:

  # Interactively initialize .gitattributes and .gitignore for your repository
  git init-config
  
  # Display help message
  git init-config --help

5. ai-usage

An interactive, responsive Terminal UI (TUI) dashboard for visualizing AI CLI usage and quota metrics in real-time. Currently, this command only supports the Google Antigravity CLI (agy).

• Options:

  • (None at the moment, just run ai-usage)

• How it works:

  1. Headless Terminal Emulation: Spawns a background tmux session to run the agy CLI invisibly.
  2. Automated Data Extraction: Continuously monitors the startup screen to parse your account profile and automatically triggers the initial /usage command.
  3. 2-Stage Prompt & Response Lifecycle Tracking:
     • Trigger 1 (Prompt Sent): Monitors ~/.gemini/antigravity-cli/history.jsonl for new token-consuming AI prompts (filtering by conversationId and ignoring non-token slash commands like /usage or /model) to fetch initial quota metrics when a prompt starts.
     • Trigger 2 (Response Completed / Timeout): Dynamically tracks ~/.gemini/antigravity-cli/brain/<conversationId>/.system_generated/logs/transcript.jsonl until the LLM finishes generating (source: MODEL, type: PLANNER_RESPONSE, status: DONE) or hits a 120-second sliding inactivity timeout (reset on any new log activity). Triggers a second /usage query to capture exact final token consumption.
  4. Dynamic Local Time Delta Calculations: Recalculates elapsed time, remaining quota countdowns, and pacing differentials (% token used vs % time passed) locally every second using high-precision local clock deltas, providing a smooth real-time TUI update.
  5. Instant Non-Blocking Controls (0ms delay): Uses OS I/O multiplexing (select.select) to instantly handle user input.
     • Use [tab] to switch between Model Groups (e.g., GEMINI MODELS vs CLAUDE AND GPT MODELS).
     • Use [f] to toggle the visibility of the Five-Hour Limit metrics.
     • Use [r] or [enter] to trigger a live manual background refresh instantly.
     • Use [esc] to cleanly exit the session.

• Examples:

  # Launch the interactive AI Usage dashboard
  ai-usage

• Example Output:

  Antigravity Usage CLI
  
  Antigravity CLI 1.1.8
  email@gmail.com (Google AI Pro)
  
  GEMINI MODELS (13.33%) | CLAUDE AND GPT MODELS (100.00%)
    Models within this group: Gemini Flash, Gemini Pro
  
    Weekly Limit
    [███████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 13.80%
      14% remaining · Refreshes in 57m
  
    Weekly Remaining
    [███████████████████████████████████████████░░░░░░░] 87.50%
    Passed: 167h (6d 23h) · Remaining: 0h 43m
    You are using tokens 12.90% slower than time elapsed (keep going!)
  
  ────────────────────────────────────────────────────────────────────────────────
  [tab] Switch Group · [f] Toggle 5-Hour Limit
  [r] or [enter] Refresh · [esc] Exit
  

6. agy-usage (Maintain Only / Deprecated)

(Note: This is the legacy one-shot print command. It is currently in maintain-only mode and may be removed in the future. Please use ai-usage instead for the full interactive experience.)

An automated script for Google Antigravity CLI (agy) usage metrics, leveraging headless PTY screen capture to parse TUI output with 0 LLM token cost and 0 API risk.

• Options:

  • --mock: Run in mock mode with sample data to test visual rendering without invoking tmux or agy.

• How it works:

  1. Headless Terminal Emulation: Spawns a background tmux PTY session (agy_usage_<PID>) at a fixed resolution (120x40) running the agy CLI.
  2. Automated Handshake & Query: Continuously polls the terminal buffer via tmux capture-pane, auto-confirms prompt trust dialogues, and sends the /usage TUI command once the CLI is ready.
  3. Regex Metric Parsing: Captures pane output upon detecting /usage response, extracts remaining Gemini quota percentage and refresh duration, and terminates the tmux session cleanly.
  4. Quota Pacing & Time Analysis: Calculates elapsed time vs. consumed quota across the 7-day (168-hour) cycle to determine your consumption pace differential (% token used vs % time passed).
  5. Rich Terminal Visuals: Prints ANSI progress bars, status spinners, remaining time metrics, and dynamic color-coded pace warnings before exiting.

• Examples:

  # Query real-time agy quota usage and pace once and exit
  agy-usage
  
  # Run in mock mode to preview UI formatting
  agy-usage --mock

• Example Output:

  [1/4] ✓ Starting headless tmux session...
  [2/4] ✓ Launching agy CLI and waiting for sign-in...
  [3/4] ✓ Querying usage via /usage command...
  [4/4] ✓ Capturing screen and parsing quota metrics...
  
  Weekly Limit
    [███████████████████████████████░░░░░░░░░░░░░░░░░░░] 62.82%
  
  Weekly Remaining
    [█████████████████████████████████░░░░░░░░░░░░░░░░░] 66.22%
    Passed: 56h (2d 8h) · Remaining: 111h (4d 15h)
  
    You are using tokens 3.40% faster than time elapsed (be careful, might run out!)
  

---

📦 Installation

Step 1: Clone the Repository

Clone the repository to your local machine:

git clone https://github.com/culur/bash.git
cd bash

Step 2: Grant Executable Permissions

Make sure the scripts have executable permissions. Run this command inside the cloned repository root:

chmod +x bin/git-fixup bin/git-out bin/git-move bin/git-init-config bin/agy-usage

Step 3: Configure to use the commands

Choose one of the following options to make the commands available in your environment:

Option A: Add the bin/ Directory to your PATH (Recommended)

Since the scripts inside the bin/ directory are prefixed with git- (git-fixup, git-out, and git-move), adding the bin/ directory directly to your shell's PATH allows Git to automatically discover them as subcommands.

Add this line to your shell configuration file (e.g., ~/.zshrc or ~/.bash_profile), replacing /path/to/cloned/bash with the actual absolute path to the directory where you cloned the repository:

export PATH="/path/to/cloned/bash/bin:$PATH"

(Tip: Or dynamically if you are in the project folder: export PATH="$(pwd)/bin:$PATH")

Then reload your configuration:

source ~/.zshrc

Option B: Register Git Aliases (Alternative)

If you prefer not to modify your shell's PATH variable, you can define Git aliases pointing directly to the scripts. Make sure to replace /path/to/cloned/bash with the actual absolute path to the directory where you cloned the repository.

Global Config (Available in all repositories)

git config --global alias.fixup "!/path/to/cloned/bash/bin/git-fixup"
git config --global alias.out "!/path/to/cloned/bash/bin/git-out"
git config --global alias.move "!/path/to/cloned/bash/bin/git-move"
git config --global alias.init-config "!/path/to/cloned/bash/bin/git-init-config"

Local Config (Only available inside a specific repository)

git config alias.fixup "!/path/to/cloned/bash/bin/git-fixup"
git config alias.out "!/path/to/cloned/bash/bin/git-out"
git config alias.move "!/path/to/cloned/bash/bin/git-move"
git config alias.init-config "!/path/to/cloned/bash/bin/git-init-config"

(Note: The ! prefix at the start of the alias command is required. It tells Git to run the script in an external shell using its absolute path.)

---

📄 License

This project is licensed under the MIT License.