Skip to content
ProGit Docs

Quick Start

From zero to managing your first project in under a minute.

1. Navigate to your git repo

Section titled “1. Navigate to your git repo”

ProGit lives alongside your existing git repositories. No separate server, no cloud account.

Terminal window
cd ~/my-project   # must be a git repo (run `git init` first if needed)

2. Initialize

Section titled “2. Initialize”
Terminal window
prog init

Creates .project/ with config and issue storage. Commit it to git — your whole team sees the same data.

3. Launch the TUI

Section titled “3. Launch the TUI”
Terminal window
prog

ProGit detects your project root, loads the .project/ data, and drops you into the TUI.

The TUI at a glance

Section titled “The TUI at a glance”
┌─ prog ──────────────────────────────────────────────────────────┐
│  [d] Dashboard  [i] Issues  [k] Kanban  [b] Branches  [a] AI   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   No issues yet. Press [n] to create your first one.           │
│                                                                 │
└──────────────── ? Help   q Quit ───────────────────────────────┘

Navigate with vim keys (j/k up/down, h/l left/right). Press ? at any time for context-sensitive help.

4. Create your first issue

Section titled “4. Create your first issue”

From anywhere in the TUI:

  1. Press i → Issues panel
  2. Press n → New issue dialog
  3. Type a title, press Enter

The issue is saved instantly to .project/issues/ as a human-readable JSON file.

5. Move it through the Kanban board

Section titled “5. Move it through the Kanban board”
  1. Press k → Kanban view
  2. Navigate to your issue with j/k
  3. Press L to move it right (Backlog → In Progress → Done)
  4. Press H to move it back

6. Use the fuzzy palette

Section titled “6. Use the fuzzy palette”

Press Ctrl+P to open the fuzzy command palette. Jump to any issue, file, commit, or action in under 200ms. This is the one feature that makes going back to the browser feel like dial-up.

7. AI assistant (optional)

Section titled “7. AI assistant (optional)”

Requires Ollama running locally:

Terminal window
ollama pull qwen2.5-coder   # or any model you prefer

Press a in the TUI to open the AI panel. Seven built-in actions: explain changes, generate tests, refactor, add docs, find bugs, optimize, generate commit message. Runs entirely local — no API keys, no cloud.

8. Sync with a forge (optional)

Section titled “8. Sync with a forge (optional)”

If you use GitLab or Forgejo:

Terminal window
export GITLAB_TOKEN=***   # or FORGEJO_TOKEN
prog sync push            # push local issues to remote
prog sync pull            # pull issues from remote

Or trigger sync from inside the TUI with Ctrl+s.

What ProGit creates

Section titled “What ProGit creates”
my-project/
├── .git/                    # your existing git repo
├── .project/                # ProGit data (commit to git)
│   ├── config.kdl           # project config
│   └── issues/              # one JSON file per issue
└── .progit/                 # local state (add to .gitignore)

The .project/ folder is designed to be committed — your whole team sees the same issues, config, and history. Issues are JSON, config is KDL. Your data, in your repo.

CLI commands

Section titled “CLI commands”

ProGit’s primary interface is the TUI. The CLI handles sync, plugins, and utilities:

Terminal window
prog                          # launch TUI (default)
prog init                     # initialize .project/ in current repo
prog sync push                # push issues to forge
prog sync pull                # pull issues from forge
prog block <issue-id>         # toggle blocked status
prog due <issue-id> 2026-04-01  # set due date
prog branch list              # list git branches
prog mr list                  # list merge requests
prog plugin list              # list installed plugins
prog hooks install            # install git hooks
prog clean                    # remove duplicate issues

Next Steps

Section titled “Next Steps”