gitbr v13

gitbr is a human-first project control center built on top of Git.

The goal is simple: a teacher, student, designer, office worker, developer, or DevOps engineer should be able to keep project history, collaborate, use AI, manage project files, connect tools, and work with Git servers without memorizing Git commands.

npm install -g gitbr-cli
gitbr

What v13 adds

v13 moves beyond a Git menu and introduces a project-control architecture:

• project intelligence and recommendations
• Simple / Standard / Expert interfaces
• project file browsing, reading, searching, editing, and configuration discovery
• main project-folder / workspace management
• project command detection and guarded execution
• safety transactions and recovery history
• safe undo onto new recovery branches
• secret scanning before external AI or remote sharing
• AI API providers
• AI CLI / agent detection
• generic external CLI integration manifests
• read-only MCP-style tool bridge for AI agents
• local and remote Git server setup over SSH
• GitHub / GitLab / generic remote support
• local responsive web dashboard
• v5 expert Git/GitHub power tools retained as gitbr legacy

The normal v13 core is Node.js and does not require Bash. Bash is only needed for the bundled legacy expert interface.

Requirements

Required:

• Node.js 18+
• Git

Optional:

• OpenSSH client/server for self-hosted collaboration
• gh for GitHub-specific operations
• glab for GitLab-specific operations
• AI CLIs such as Claude Code, Codex CLI, Gemini CLI, Aider, OpenCode, or Ollama
• Bash for gitbr legacy

Interface levels

Simple

For users who do not know Git terminology. It speaks in terms such as:

• Save my work
• Send my work to the team
• Get the latest team changes
• See previous versions
• Undo / safety
• Files & configuration
• Ask AI
• Project folders
• Team / server

Standard

Uses commit, branch, sync, remote, and other normal Git terms while preserving safe workflows.

Expert

Launches the bundled advanced Git + GitHub interface with staging, hunks, rebase, stash, reflog, worktrees, submodules, LFS, PRs, issues, Actions, releases, repository maintenance, and recovery operations.

gitbr mode simple
gitbr mode standard
gitbr mode expert

Everyday project commands

gitbr
gitbr init
gitbr status
gitbr project
gitbr plan "share my work"
gitbr save -m "Updated lesson notes"
gitbr sync
gitbr share -m "Chapter 5"
gitbr history
gitbr restore
gitbr do "save and send my work to the team"

gitbr restore creates a new recovery branch instead of deleting newer history.

Project intelligence

gitbr project

The project engine detects useful context including:

• repository state
• current branch / upstream
• ahead / behind counts
• conflicts
• project language/framework markers
• package manager
• common configuration files
• package scripts
• recommended next action

Examples of detected project markers include Node.js, Python, Go, Rust, PHP, Ruby, Java, Kotlin, Flutter/Dart, Docker, Make, and CMake.

Files and configuration

gitbr files tree
gitbr files tree --depth 5
gitbr files list src
gitbr files read README.md
gitbr files find authentication
gitbr search "login form"
gitbr files edit src/app.js
gitbr files configs

gitbr files edit uses $VISUAL or $EDITOR.

File paths are restricted to the current project root, so ../ cannot be used to escape the project through the file API.

Project commands

For Node-based projects, gitbr detects scripts from package.json:

gitbr commands list
gitbr commands run test
gitbr commands run lint
gitbr commands run build

Commands are classified as:

• safe — tests, lint, type checks, formatting, validation
• confirm — normal project commands
• dangerous — commands whose names/content suggest reset, delete, deployment, migration, production, release, and similar operations

Non-safe commands require confirmation unless explicitly approved.

Main project folders / workspace

Register the folders where you keep projects:

gitbr workspace add ~/Projects
gitbr workspace add ~/School
gitbr workspace roots
gitbr workspace scan

The scanner finds Git repositories and common project folders under configured roots.

This allows gitbr to act as a project launcher/control center instead of requiring users to remember every project path.

Safety points, transactions, and undo

Important v13 workflows attempt to create a safety point before changing repository state.

gitbr undo list
gitbr undo restore 178839...

Safety history records:

• action
• start/end time
• workflow steps
• before state
• after state
• failure information

Dirty working states are stored using Git objects under private refs/gitbr/snapshots/* references rather than leaving visible git stash entries behind.

Restoring a safety point creates a new recovery branch. It does not intentionally rewind a shared branch.

Secret scanning

gitbr secrets scan

The scanner looks for likely sensitive material such as:

• private keys
• AWS access keys
• GitHub/GitLab/npm/Slack token patterns
• suspicious API key / password / token assignments
• .env files
• .pem, .key, credentials, and secret-style filenames

It is intentionally heuristic. A match is a reason to review a file, not proof that a secret is valid.

By default:

• external AI repository context is blocked when likely secrets are detected
• sharing workflows scan for likely secrets
• non-interactive --yes sharing remains blocked unless the safety policy is deliberately changed

AI providers

Configure a provider:

gitbr ai setup

Built-in provider adapters include:

• OpenAI
• Anthropic
• Google Gemini
• OpenRouter
• Groq
• Mistral
• Ollama
• custom OpenAI-compatible APIs

Examples:

gitbr ask "what changed in this project?"
gitbr ai review
gitbr ai commit
gitbr ai agent "save my work and synchronize it"
gitbr ai providers

API credentials are read from environment variables and are not written into the project configuration by gitbr.

Common variables include:

export OPENAI_API_KEY="..."
export ANTHROPIC_API_KEY="..."
export GEMINI_API_KEY="..."
export OPENROUTER_API_KEY="..."
export GROQ_API_KEY="..."
export MISTRAL_API_KEY="..."
export GITBR_AI_API_KEY="..."

Ollama can be used for local processing.

AI CLIs and agents

v13 can detect installed AI/developer CLIs instead of forcing all integrations through cloud APIs.

gitbr agents list
gitbr integrations list

Built-in detection/adapters currently include:

• Claude Code
• OpenAI Codex CLI
• Gemini CLI
• Aider
• OpenCode
• Ollama
• GitHub CLI
• GitLab CLI
• Docker
• Podman
• VS Code

The architecture is extensible. An AI CLI does not need to be compiled into gitbr to be usable.

Running an external AI agent

gitbr agents run claude-code "review this project"

External AI CLI execution is an explicit trust boundary. Interactive runs show the adapter and declared permissions first.

Generic integration execution is disabled by default:

gitbr config set integrations.allowExternalCommands true

Only enable it if you understand the external tools you install.

Custom integration manifests

Install a JSON integration manifest:

gitbr integrations add examples/integration.example.json
gitbr integrations list

A manifest can describe:

• executable
• integration type
• version command
• prompt argument template
• declared permissions
• environment additions

Example:

{
  "id": "my-ai",
  "label": "My AI CLI",
  "type": "ai-cli",
  "command": "my-ai",
  "versionArgs": ["--version"],
  "promptArgs": ["run", "{prompt}"],
  "permissions": ["files:read", "files:write"]
}

The placeholders supported by prompt arguments are:

• {prompt}
• {model}
• {cwd}

Custom manifests live under the user's gitbr configuration directory, not inside every repository.

Custom agent manifests

Agents wrap integrations with a user-visible identity and permission mode.

gitbr agents add examples/agent.example.json
gitbr agents list
gitbr agents run my-agent "inspect the repository"

This makes it possible to configure multiple agents backed by different AI CLIs or local tools.

MCP-style AI tool bridge

Run from a project:

gitbr mcp serve

The v13 bridge communicates over JSON-RPC on stdio and exposes a deliberately read-only set of project tools:

• project_status
• project_tree
• file_read
• file_search
• git_diff
• git_history
• secret_scan
• safety_history

It implements the core initialize, tools/list, tools/call, and ping message flow used by MCP-style tool clients.

Write operations are intentionally not exposed through the v13 bridge. External agents can inspect the project without automatically receiving commit, push, reset, delete, shell, server, or credential capabilities.

Future integrations can add controlled write capabilities behind the same permission/transaction engine.

Project-specific configuration

v13 stores shareable project metadata under:

.gitbr/project.json

This can contain project commands, AI instructions, team metadata, project preferences, and server metadata.

Machine-specific state remains outside the repository:

~/.config/gitbr/
~/.local/share/gitbr/
~/.cache/gitbr/

Environment variables can override these locations:

GITBR_CONFIG_DIR=/custom/config
GITBR_DATA_DIR=/custom/data
GITBR_CACHE_DIR=/custom/cache

Local Git server

Create a shared bare repository on the current computer:

gitbr server local

Custom location:

gitbr server local --root ~/gitbr-server/repos --name school-history

For network collaboration, use standard authenticated Git-over-SSH. gitbr does not invent a custom Git transport.

gitbr server enable-ssh
gitbr server trust [email protected]
gitbr server status

Remote SSH server setup

gitbr server setup [email protected]

gitbr can verify the account, create a repository storage directory, create a bare Git repository, and attach it as a remote.

Authentication/authorization remain enforced by the server's normal SSH/account configuration.

Team metadata

gitbr team list
gitbr team add
gitbr team remove
gitbr team invite

Roles include viewer, contributor, maintainer, admin, and owner.

These labels are project metadata. They are not a replacement for server-side SSH/hosting permissions.

GitHub, GitLab, and generic remotes

gitbr forge

• GitHub integrations use gh when available.
• GitLab integrations use glab when available.
• Gitea, Forgejo, generic SSH servers, and other Git remotes continue to work through normal Git operations.

Local web dashboard

gitbr web

The v13 dashboard shows project type, branch, saved state, remote state, recommendation, detected configuration files, and recent history.

By default it binds to localhost only.

gitbr web --lan --port 4777

LAN mode is deliberate and can expose repository metadata to other devices on the network.

Plugins

JavaScript plugins are disabled by default because they execute with the operating-system permissions of the current user.

gitbr plugins status
gitbr plugins enable
gitbr plugins disable

Plugin directory:

~/.config/gitbr/plugins/

Diagnostics

gitbr doctor

The v13 doctor reports Git, SSH, forge CLIs, AI provider, detected AI CLIs, external-command policy, config/data paths, safety-history count, repository state, and remote state.

Environment variables

Useful variables:

NO_COLOR=1
GITBR_NO_CLEAR=1
GITBR_NUMBERED_MENUS=1
GITBR_DEBUG=1
GITBR_CONFIG_DIR=/path
GITBR_DATA_DIR=/path
GITBR_CACHE_DIR=/path
GITBR_BASH=/path/to/bash

Design principle

The user should describe what they want to accomplish. gitbr should decide which safe Git/project operations are necessary.

The same project core is intended to serve:

• human interactive users
• command-line automation
• AI API providers
• external AI CLIs
• generic integrations
• MCP-style agents
• local web UI
• future native/server interfaces

See SECURITY.md before enabling external agents, LAN access, plugins, or server setup.