Geeto

A guided Git workflow for consistent branches, commits, reviews, releases, and cleanup.

Geeto turns working-tree changes into a clean, merged branch through one interactive CLI. It handles the repetitive Git steps, uses your preferred AI provider for suggestions, and keeps every action available as a standalone command when you need more control.

Stage → Branch → Commit → Push → Merge → Cleanup

Install

brew tap IDNCraft/geeto
brew trust --formula idncraft/geeto/geeto
brew install geeto

Or install from npm:

npm install -g geeto

Requires Git 2.0 or newer. npm installations also require Node.js 18 or newer. See all installation methods for Bun, APT, standalone binaries, and source builds.

Quick Start

Run Geeto inside a Git repository:

geeto

On the first run, choose an AI provider and follow the guided workflow. Geeto previews generated branch names, commit messages, and release notes before applying them.

Watch the terminal demo

Contents

• Why Geeto
• Workflow
• AI Providers
• CLI Reference
• Configuration
• Installation
• Migrating from rust142
• Development

Why Geeto

• Finish the whole branch lifecycle — Move from local changes to a merged branch without manually chaining Git commands.
• Keep humans in control — Review generated names, messages, and release notes before Geeto writes or publishes anything.
• Use the provider you already trust — Choose Gemini, OpenRouter, Groq, OpenAI Codex, or OpenCode Zen.
• Recover interrupted work — Resume a saved checkpoint instead of repeating completed steps.
• Stay in one interface — Manage GitHub, GitLab, releases, Trello tasks, and everyday Git utilities from the terminal.

Workflow

Running geeto starts six guided steps:

1. Stage — Review working-tree changes and choose what to stage.
2. Branch — Generate, edit, or manually enter a branch name.
3. Commit — Generate and approve a Conventional Commit message.
4. Push — Push the working branch to its remote.
5. Merge — Select a target branch and complete the merge.
6. Cleanup — Remove merged branches when they are no longer needed.

Geeto saves progress between steps. Use geeto --resume after an interruption or geeto --fresh to ignore the saved checkpoint. Every workflow step is also available as a standalone command.

AI Providers

Geeto supports five provider integrations:

| Provider | Authentication | Runtime notes | | ---------------- | ---------------------------------------------------- | --------------------------------------------------- | | Gemini | Google AI Studio API key | Project-local or global config | | OpenRouter | OpenRouter API key | Project-local or global config | | Groq | Groq API key | Project-local or global config | | OpenAI Codex | OpenAI API key or Codex CLI OAuth with codex login | Generation runs with an isolated Geeto runtime home | | OpenCode Zen | Free access or OpenCode Zen API key | Runs in an isolated Geeto runtime environment |

Generated content remains reviewable before use. Change providers or model favorites from the interactive settings menu, or use geeto --change-model and geeto --sync-models directly.

CLI Reference

Workflow

| Command | Description | | -------------------- | ------------------------------- | | geeto | Full workflow (all 6 steps) | | geeto -s, --stage | Stage files interactively | | geeto -sa, -as | Stage all changes automatically | | geeto -c, --commit | Create commit with AI message | | geeto -b, --branch | Create branch with AI name | | geeto -p, --push | Push current branch to remote | | geeto -m, --merge | Merge branches interactively |

Git Tools

| Command | Description | | -------------------------- | ----------------------------------- | | geeto -cl, --cleanup | Clean up local & remote branches | | geeto -sw, --switch | Switch branches with fuzzy search | | geeto -cmp, --compare | Compare current branch with another | | geeto -cp, --cherry-pick | Cherry-pick from another branch | | geeto -lg, --log | View commit history with timeline | | geeto -sh, --stash | Manage stashes interactively | | geeto -am, --amend | Amend the last commit | | geeto -rw, --reword | Edit past commit messages | | geeto -u, --undo | Undo the last git action safely | | geeto -rv, --revert | Revert the last commit (soft reset) | | geeto -al, --alias | Install shell aliases for geeto | | geeto -sts, --stats | Repository statistics dashboard | | geeto -st, --status | Pretty git status overview | | geeto -pl, --pull | Pull from remote interactively | | geeto -ft, --fetch | Fetch latest from remote | | geeto -sm, --submodules | Manage Git submodules | | geeto --abort | Abort in-progress operation | | geeto --prune | Remove stale remote branches |

GitHub / GitLab

| Command | Description | | ---------------------------- | ----------------------------------------------------------------------- | | geeto -pr, --pr | Create a Pull Request (GitHub) or Merge Request (GitLab) | | geeto -rvp, --review-pr | Review and comment on a Pull Request or Merge Request with AI | | geeto -rvi, --review-issue | Review and comment on an Issue with AI | | geeto -i, --issue | Create an Issue | | geeto -t, --tag | Manage semver releases, changelogs, tags, and GitHub or GitLab Releases | | geeto -rp, --repo | Update repository description, topics, and homepage |

Trello

| Command | Description | | ------------------------------ | --------------------------- | | geeto -tr, --trello | Open Trello menu | | geeto -tg, --trello-generate | Generate AI agent task list |

Settings

| Command | Description | | -------------------------- | ----------------------------------------------- | | geeto --setup-gemini | Configure Gemini | | geeto --setup-openrouter | Configure OpenRouter | | geeto --setup-groq | Configure Groq | | geeto --setup-codex | Configure OpenAI Codex with an API key or OAuth | | geeto --setup-opencode | Configure free or API-key OpenCode Zen access | | geeto --setup-github | Configure GitHub access | | geeto --setup-gitlab | Configure GitLab access and instance URL | | geeto --setup-trello | Configure Trello access and board | | geeto --change-model | Switch AI provider or model | | geeto --sync-models | Refresh available provider models | | geeto --separator | Set the branch-name separator |

Options

| Command | Description | | ---------------------- | ----------------------------------- | | geeto -f, --fresh | Start fresh (ignore checkpoint) | | geeto -r, --resume | Resume from last checkpoint | | geeto -dr, --dry-run | Simulate commands without executing | | geeto -v, --version | Show version + update status | | geeto -h, --help | Show help |

Management

| Command | Description | | --------------------- | ----------------------------------- | | geeto -up, --update | Update geeto to the latest version | | geeto --where | Show installation path & method | | geeto --uninstall | Uninstall geeto with auto-detection |

Trello Integration

Turn selected Trello cards into individual Markdown task files:

geeto --trello-generate

Geeto preserves each card's description and checklists, then writes one file per card to .geeto/tasks/.

The project-level .geeto/ directory is added to .gitignore automatically.

Configuration

Gemini, OpenRouter, Groq, GitHub, and GitLab support project and user-level configuration. Project-local config takes priority:

| Location | Scope | Priority | | ----------- | --------------------- | ----------------------------------- | | .geeto/ | Project-local | Higher — overrides global | | ~/.geeto/ | Global (all projects) | Fallback when no local config found |

Use global config for shared credentials, then override individual projects when needed. OpenAI Codex and OpenCode Zen access stays user-level. Trello, branch strategy, checkpoints, and model favorites stay project-local.

Run a --setup-* command for direct setup, or open Configure providers, integrations, and defaults from the main menu. Geeto adds project-local .geeto/ data to .gitignore; ~/.geeto/ remains outside the repository.

Config files

| File | Created by | Purpose | | ---------------------- | ------------------------- | ------------------------------------------------------------------------- | | gemini.toml | --setup-gemini | Gemini API key | | openrouter.toml | --setup-openrouter | OpenRouter API key | | groq.toml | --setup-groq | Groq API key | | codex.toml | --setup-codex | Global OpenAI Codex authentication state | | opencode-zen.toml | --setup-opencode | Global validated OpenCode Zen access state | | github.toml | --setup-github | GitHub personal access token | | gitlab.toml | --setup-gitlab | GitLab token + instance URL | | trello.toml | --setup-trello | Project-local Trello API key, token, and board ID | | branch-strategy.toml | --separator / first run | Branch separator char and last naming strategy (project-only, not global) |

State & cache files

These are always project-local — not read from ~/.geeto/.

| File | Created by | Purpose | | ------------------------- | --------------------------------- | ------------------------------------------------------------------------ | | geeto-state.json | Automatically | Checkpoint state for workflow recovery (-r, --resume) | | openrouter-model.json | --sync-models | Persisted OpenRouter model list (filtered, text/code only) | | gemini-model.json | --sync-models | Persisted Gemini model list | | groq-model.json | --sync-models | Persisted Groq model list | | codex-model.json | --setup-codex / --sync-models | Persisted OpenAI Codex model list | | opencode-model.json | --sync-models | Persisted OpenCode Zen model favorites | | last-ai-suggestion.json | Every AI call | Last raw AI response — inspect when branch/commit suggestions look wrong |

Installation

Choose the package that matches your environment:

Homebrew

brew tap IDNCraft/geeto
brew trust --formula idncraft/geeto/geeto
brew install geeto

If the legacy tap is still installed, remove it before installing Geeto:

brew untap rust142/geeto
brew install idncraft/geeto/geeto

npm or Bun

npm install -g geeto
# or
bun install -g geeto

Debian or Ubuntu

Download the latest .deb package for amd64 or arm64 from GitHub Releases, then install it:

sudo dpkg -i geeto_<version>_<architecture>.deb

Standalone Binary

Download the matching binary from GitHub Releases:

| Platform | Binary | | ----------- | ------------------- | | macOS x64 | geeto-mac | | macOS ARM64 | geeto-mac-arm64 | | Linux x64 | geeto-linux | | Linux ARM64 | geeto-linux-arm64 | | Windows x64 | geeto-windows.exe |

On macOS or Linux, make the downloaded binary executable and move it into PATH:

chmod +x geeto-<platform>
sudo mv geeto-<platform> /usr/local/bin/geeto

From Source

git clone https://github.com/IDNCraft/geeto.git
cd geeto
bun install
bun run build
bun link

Requirements

| Installation method | Requirements | | ------------------- | ----------------------------- | | Homebrew / .deb | Git 2.0 or newer | | Standalone binary | Git 2.0 or newer | | npm | Node.js 18 or newer, Git 2.0+ | | Bun / source | Bun 1.0 or newer, Git 2.0+ |

Migrating from rust142

Geeto moved from rust142/geeto to IDNCraft/geeto. Existing .geeto/ project and user configuration remains compatible; do not delete it during migration.

Homebrew

Remove the legacy formula and tap, then install from IDNCraft:

brew uninstall geeto
brew untap rust142/geeto
brew tap IDNCraft/geeto
brew trust --formula idncraft/geeto/geeto
brew install idncraft/geeto/geeto

npm or Bun

The package name remains geeto, so reinstalling updates the existing global package:

npm install -g geeto@latest
# or
bun install -g geeto@latest

Source checkout

Point the existing clone at the new repository before pulling updates:

git remote set-url origin [email protected]:IDNCraft/geeto.git
git remote -v
git pull

Standalone binary or Debian package

Download the replacement binary or .deb from IDNCraft releases and install it over the previous version.

Verify the migrated installation:

geeto --version

Maintenance

Geeto detects the active installation method for updates, diagnostics, and removal:

geeto --update       # Install the latest available version
geeto --where        # Show binary, version, config path, and install method
geeto --uninstall    # Remove Geeto after confirmation

Use geeto --version to print the installed version and update status. During uninstall, Geeto asks separately whether it should remove configuration and shell aliases.

Development

git clone https://github.com/IDNCraft/geeto.git
cd geeto
bun install

bun run build          # Build
bun run dev            # Development mode (run from source)
bun run check:fast     # Formatting, TypeScript, Markdown, and YAML lint
bun run check:full     # Typecheck + production build

See CONTRIBUTING.md for detailed guidelines.

Contributing

1. Fork the repository
2. Create a branch: dev#your-feature
3. Make your changes
4. Run checks: bun run check:fast && bun run check:full
5. Submit a Pull Request to main branch

See CONTRIBUTING.md for details.

Support

If Geeto helps your workflow, consider supporting:

• ☕ Buy me a coffee on Saweria
• ⭐ Star this repository
• 🐛 Report bugs or suggest features

License

MIT — see LICENSE for details.