Skip to content
ProGit Docs

Quick Start

This guide will get you from zero to managing your first project in under 5 minutes.

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. Launch ProGit

Section titled “2. Launch ProGit”
Terminal window
prog

That’s it. prog automatically detects your project root, creates a .project/ directory the first time, 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.

3. Create your first issue

Section titled “3. 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 KDL file.

4. Move it through the Kanban board

Section titled “4. 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

5. Work with branches

Section titled “5. Work with branches”

Press b to open the branch panel. ProGit shows all your local git branches and lets you switch between them without leaving the terminal.

For virtual branches (work-in-progress on multiple features simultaneously):

  1. Press b → Branch panel
  2. Press v → Create virtual branch
  3. Give it a name

Virtual branches track file-level changes without creating actual git branches — no stashing, no context switching friction.

6. Sync with a forge (optional)

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

If you use GitLab or Forgejo, set your token and run a sync:

Terminal window
export GITLAB_TOKEN="glpat-xxxxxxxxxxxx"
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.

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. Ask anything — commit message suggestions, code review, bug explanation.

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 .kdl file per issue
└── .progit/                 # local cache (add to .gitignore)
    └── issues.json          # JSON mirror for fast queries

The .project/ folder is designed to be committed — your whole team sees the same issues, config, and history.

CLI commands

Section titled “CLI commands”

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

Terminal window
prog                          # launch TUI (default)
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”