@ginkoai/cli

v2.5.0

Published

5 days ago

Git-native session management and cloud context for AI-mediated development. AI Collaboration for Vibe Tribes.

0High
0Medium
0Low

ginkoaichris

ai development git privacy cli context session handoff reflection claude copilot cursor

Ginko CLI

Privacy-first CLI for AI-assisted development. Your code never leaves your machine.

Installation

npm install -g @ginkoai/cli
# or
npm link  # for development

Quick Start

# Initialize Ginko in your project
ginko init

# Start a session
ginko start

# Save progress
ginko handoff "Completed authentication feature"

# Check status
ginko status

Core Commands

Session Management

ginko init - Initialize Ginko in your project
ginko start [sessionId] - Start or resume a session
ginko handoff [message] - Create a session handoff
ginko status - Show current session status
ginko log [description] - Log events to session (ADR-033 defensive logging)

Planning & Organization

ginko charter - Create and manage project charter (AI-assisted)
- Default: Output template for AI-mediated conversation
- --view - View existing charter
- --edit - Edit charter conversationally
- --no-ai - Interactive CLI mode
ginko epic - Create and manage epics with sprint breakdown (AI-assisted)
- Default: Output template for AI-mediated conversation
- --list - List existing epics
- --view - View epic details with sprint progress
- --sync - Sync epic to graph database

Context & Configuration

ginko context - Manage session context
- --add <files...> - Add files to context
- --remove <files...> - Remove files from context
- --show - Show current context
ginko config - Manage Ginko configuration
- --get <key> - Get config value
- --set <key> <value> - Set config value
- --list - Show all configuration

Workflow Commands

ginko vibecheck [concern] - Quick recalibration when feeling lost
ginko compact - Reduce context size and clean up old sessions
- --preserve <files...> - Keep specific files
- --aggressive - More aggressive cleanup
ginko ship [message] - Create and push PR-ready branch
- --branch <name> - Specify branch name
- --no-push - Skip pushing to remote
- --no-tests - Skip running tests

Multi-Agent Orchestration (EPIC-004)

Enable multiple AI agents to collaborate on complex projects.

ginko agent - Manage AI agents
- register - Register agent with capabilities
- list - List agents (filter by status/capability)
- status - Show current agent details
- work - Start worker mode (poll for tasks)
ginko orchestrate - Run as supervisor agent
- --epic <id> - Target specific epic
- --dry-run - Preview without executing
- --resume - Resume from checkpoint
ginko verify <taskId> - Verify task acceptance criteria
ginko checkpoint - Manage work state snapshots
- create - Create checkpoint before risky changes
- list - List checkpoints
- show - View checkpoint details
ginko escalation - Request human intervention
- create - Create escalation with severity
- list - List open/resolved escalations
- resolve - Record human decision
ginko dlq - Manage failed events (Dead Letter Queue)
- list - Show failed events
- retry - Retry specific or all entries
- stats - DLQ statistics
ginko notifications - Human observability
- list - Show configured hooks
- test - Test notification delivery
- history - View delivery log

See Multi-Agent Orchestration Guide for details.

Team Collaboration (EPIC-008)

Enable teams to share knowledge while keeping sessions private.

ginko invite - Invite collaborators to your team
- <email> - Invite by email address
- --role <role> - Assign role: owner, admin, member
- --list - List pending invitations
- --revoke <code> - Cancel an invitation
ginko join - Join a team using an invitation code
- <code> - Accept invitation
- --yes - Skip confirmation prompt
ginko teams - Manage teams
- create <name> - Create a new team
- list - List your teams
- add-member <team> <user> - Add member by GitHub username
- remove-member <team> <user> - Remove a team member
- list-members <team> - List team members
- add-to-project <team> <project> - Grant team access
- remove-from-project <team> <project> - Revoke access
ginko sync - Pull dashboard edits to local git
- --dry-run - Preview what would be synced
- --force - Overwrite local files
- --type <type> - Sync only: ADR, PRD, Pattern, Gotcha, Charter, Sprint
- --no-commit - Skip auto-commit

See Team Collaboration Guide for details.

Features

Privacy First

No code leaves your machine - All data stored locally in .ginko/ directory
Git-native persistence - Session handoffs tracked in git
Zero analytics by default - Complete privacy, no telemetry

AI Adaptability

Ginko automatically detects and adapts output for:

Claude (markdown with colors)
GPT-4 (structured JSON)
Gemini (hierarchical XML)
Llama (minimal format)
Universal fallback

Session Archives

Handoffs are archived with human-readable names:

2025-08-27-fix-auth-bug.md
2025-08-27-implement-payment.md
2025-08-27-refactor-database.md

Monorepo Compatible

NEW in v1.1.2 - All commands work from any subdirectory:

Run ginko commands from anywhere in your monorepo
Automatically detects git repository root
Session data stored at repository root for consistency
No more "file not found" errors in multi-package repos

# Works from any subdirectory
cd packages/frontend
ginko start              # ✓ Works perfectly

cd ../backend
ginko log "Fix API"      # ✓ Same session, correct location

cd ../../
ginko status             # ✓ Consistent across directories

Directory Structure

.ginko/
├── sessions/           # Session handoffs and archives
│   └── user-email/
│       ├── current.md  # Latest handoff
│       └── archive/    # Previous sessions
├── context/            # Context management
│   ├── current.json    # Active context files
│   └── modules/        # (Future) Persistent context modules
├── patterns/           # Discovered patterns
├── best-practices/     # Team standards
└── config.json         # User preferences

Configuration

Default configuration (.ginko/config.json):

{
  "version": "0.1.0",
  "user": {
    "email": "[email protected]"
  },
  "privacy": {
    "analytics": {
      "enabled": false,
      "anonymous": true
    },
    "telemetry": {
      "enabled": false
    }
  },
  "git": {
    "autoCommit": false,
    "signCommits": false
  },
  "ai": {
    "model": "auto-detect",
    "output": {
      "format": "human",
      "colors": true,
      "emojis": true
    }
  }
}

Workflow Examples

Basic Development Flow

ginko init                          # Set up project
ginko start                         # Begin work
# ... do development work ...
ginko handoff "Implemented feature" # Save progress

Debugging Session

ginko start
# ... encounter issues ...
ginko vibecheck "stuck on async bug"  # Get recalibration
# ... fix issues ...
ginko handoff "Fixed async race condition"

Shipping Changes

ginko ship "Add user authentication"  # Creates PR
# Automatically:
# - Runs tests
# - Commits changes
# - Creates feature branch
# - Pushes to remote
# - Opens pull request

Managing Context

ginko context --add "src/auth/*"      # Track auth files
ginko context --show                  # View tracked files
ginko compact                          # Clean up old context

Planning with Epics

ginko epic                           # AI guides epic creation conversation
# AI asks about goals, success criteria, scope, sprints
# Creates docs/sprints/EPIC-XXX-name.md and sprint files

ginko epic --list                    # List all epics
ginko epic --view                    # View epic with sprint progress
ginko epic --sync                    # Sync to graph database

Project Charter

ginko charter                        # AI guides charter conversation
# AI asks about purpose, users, success criteria, scope
# Creates docs/PROJECT-CHARTER.md

ginko charter --view                 # View existing charter
ginko charter --edit                 # Refine charter conversationally

Future Features

Persistent Context Modules (Coming Soon)

Modular "memory cards" that persist learnings across sessions:

Architecture decisions
Configuration details
Common gotchas
Code patterns
Team standards

# Future commands:
ginko context load auth              # Load auth knowledge
ginko context capture "JWT gotcha"   # Save learning
ginko context auto                   # Auto-detect needed context

Development

# Clone repository
git clone https://github.com/ginkoai/ginko
cd ginko/packages/cli

# Install dependencies
npm install

# Build TypeScript
npm run build

# Link for local testing
npm link

# Test commands
ginko --help

Privacy Guarantee

What NEVER leaves your machine:

❌ Source code
❌ File contents
❌ File paths or names
❌ Commit messages
❌ API keys or secrets
❌ Session content
❌ Any proprietary information

What can be shared (opt-in only):

✅ Anonymous usage metrics (if enabled)
✅ Command frequency
✅ Session duration
✅ Performance statistics

Support

Report issues: https://github.com/ginkoai/ginko/issues
Documentation: https://docs.ginko.ai
Email: [email protected]

License

MIT - See LICENSE file for details

Built with 🌱 by Ginko AI - Privacy-first tools for AI-assisted development