# Tigs Python Package
Tigs (Talks in Git → Specs) is a CLI tool for storing and managing LLM chats in Git associated with code commits.
## Why Tigs?
The biggest bug in software engineering isn't a crash — it's forgetting why. When someone asks "Why is this function designed this way?", too often the answer is "I think the AI suggested it?"
Tigs solves this by:
- **Preserving decision rationale** - Never lose that god-tier prompt or design debate
- **Creating traceable history** - Every "why" has a link you can follow
- **Accelerating onboarding** - New contributors understand the conversation, not just the code
- **Building prompt libraries** - Your best AI interactions become reusable team assets
## Key Features
- **Non-invasive storage** - Uses Git notes; never rewrites your commits
- **Fast TUI interface** - Navigate commits, select chats, and link them effortlessly
- **Tool-agnostic** - Works with chats from Claude Code, Gemini CLI, Qwen Code and more
- **Version-controlled context** - Your reasoning becomes greppable, diffable, and reviewable
- **Future: Auto-generated specs** - AI will read commits + chats to generate precise system specifications
## Installation
```bash
pip install tigs # or: pipx install tigs
```
## Quick Start
Tigs provides two main interactive TUI (Terminal User Interface) commands:
With Claude Code, run `tigs` inside any directory of a Git repo that has Claude Code sessions.
All your chat history associated with the repo will be loaded and ready to store with commits!
### `tigs store` - Select and Store Chats
Launch an interactive interface to select commits and messages to associate with code commits:
```bash
tigs store
```
The store interface features:
- **Three-pane layout**: Commits (left), Messages (center), Logs (right)
- **Keyboard navigation**:
- `j/k` or `↑/↓` - Navigate up/down
- `Space` - Toggle selection
- `v` - Visual selection mode
- `a` - Select all
- `c` - Clear selections
- `Tab` - Switch between panes
- `s` - Store selected items as a chat
- `q` - Quit
### `tigs view` - Browse and Read Chats
Explore existing chats associated with your commits:
```bash
tigs view
```
The view interface displays:
- **Three-column layout**: Commits list, Commit details, Chat content
- **Navigation**: Browse through commits and view associated chats
- **Read-only mode**: Safely explore without modifying data
### Provider discovery
Tigs reads chat histories through `cligent` adapters. Out of the box the
logs pane surfaces sessions from Claude Code, Gemini CLI, and Qwen Code when
those logs exist locally, including nested Claude project folders that match
the current directory's prefix.
To restrict the scan to specific adapters, set the `TIGS_CHAT_PROVIDERS`
environment variable before launching the TUI:
```bash
# Example: only show Claude Code conversations
TIGS_CHAT_PROVIDERS=claude-code tigs store
```
Every entry in the logs pane includes a provider label so you can quickly
spot which tool produced a session. Set `TIGS_CHAT_RECURSIVE=0` if you prefer
to limit discovery to the exact project directory you launched Tigs from.
## Syncing with Remote Repositories
Share your chats across team members using Git-native sync workflow:
```bash
# Pull (fetch + merge) chats from remote
tigs pull # Default: union strategy (preserves all conversations)
# Or specify merge strategy
tigs pull --strategy=ours # Keep local on conflict
tigs pull --strategy=theirs # Keep remote on conflict
# Push chats to remote repository
tigs push
```
### How Sync Works
- **`tigs fetch`**: Downloads remote notes to staging namespace (`refs/notes-remote/<remote>/chats`) - safe, read-only
- **`tigs pull`**: Fetches and merges using git notes merge strategies
- `union` (default): Combines all conversations separately, no message mixing
- `ours`: Keep local notes on conflict
- `theirs`: Keep remote notes on conflict
- `manual`: Require manual resolution
- **`tigs push`**: Uploads your local notes to remote
The `push` command validates that all commits with chats are pushed to the remote before pushing the notes, preventing orphaned references.
**Multi-user workflow**: Each user's chat is preserved as an independent conversation. The default `union` strategy combines all chats using YAML multi-document format, ensuring no messages are mixed across different conversations.
## Low-Level Commands
For automation and scripting, Tigs provides direct CLI commands:
```bash
# Add chat to current commit (HEAD)
tigs add-chat -m "Chat content in YAML format"
# Add chat to specific commit
tigs add-chat abc123 -m "Chat content"
# Show chat for current commit
tigs show-chat
# Show chat for specific commit
tigs show-chat abc123
# List all commits that have chats
tigs list-chats
# Remove chat from commit
tigs remove-chat abc123
```
### Interactive Editor
If you don't provide the `-m` flag, tigs opens your default editor:
```bash
# Opens editor for chat content
tigs add-chat
```
## Chat Format
Chats are stored in YAML format following the `tigs.chat/v1` schema:
```yaml
schema: tigs.chat/v1
messages:
- role: user
content: What does this commit implement?
- role: assistant
content: This commit adds authentication using JWT tokens.
```
## Git Integration
Tigs stores chats as Git notes in `refs/notes/chats`, which means:
- **Version controlled**: Chats are part of Git history
- **Distributed**: Push/pull chats like any Git data
- **Non-invasive**: Doesn't modify commits or require rebasing
- **Compatible**: Works with any Git workflow
- **Efficient**: Git's fanout structure handles large scale
You can also use standard Git commands:
```bash
# View notes directly
git notes --ref=refs/notes/chats show <commit>
# Push notes manually
git push origin refs/notes/chats
```
## Use Cases
- **Code Review**: Attach review discussions with LLM to specific commits
- **Documentation**: Add design & implementation notes and decisions
- **Learning**: Annotate commits with explanations for team members
- **AI Assistance**: Store AI conversations about code changes
- **Debugging**: Keep notes about bug investigations tied to commits
## Requirements
- Python 3.8+
- Git 2.17+
- Terminal with UTF-8 support
- Unix-like system (Linux, macOS, WSL)
Raw data
{
"_id": null,
"home_page": null,
"name": "tigs",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ai, chat, chatgpt, claude, development-tools, gemini, git, llm, prompts, qwen, software-development, spec-driven, specifications, specs, version-control, vibe-coding",
"author": null,
"author_email": "SubLang Community <hi@sublang.ai>",
"download_url": "https://files.pythonhosted.org/packages/e3/1d/faa4be1189da3cdb0c949633256b2436e043f48b7abb426e57572f6b9388/tigs-0.1.4.tar.gz",
"platform": null,
"description": "# Tigs Python Package\n\nTigs (Talks in Git \u2192 Specs) is a CLI tool for storing and managing LLM chats in Git associated with code commits.\n\n## Why Tigs?\n\nThe biggest bug in software engineering isn't a crash \u2014 it's forgetting why. When someone asks \"Why is this function designed this way?\", too often the answer is \"I think the AI suggested it?\"\n\nTigs solves this by:\n- **Preserving decision rationale** - Never lose that god-tier prompt or design debate\n- **Creating traceable history** - Every \"why\" has a link you can follow\n- **Accelerating onboarding** - New contributors understand the conversation, not just the code\n- **Building prompt libraries** - Your best AI interactions become reusable team assets\n\n## Key Features\n\n- **Non-invasive storage** - Uses Git notes; never rewrites your commits\n- **Fast TUI interface** - Navigate commits, select chats, and link them effortlessly\n- **Tool-agnostic** - Works with chats from Claude Code, Gemini CLI, Qwen Code and more\n- **Version-controlled context** - Your reasoning becomes greppable, diffable, and reviewable\n- **Future: Auto-generated specs** - AI will read commits + chats to generate precise system specifications\n\n## Installation\n\n```bash\npip install tigs # or: pipx install tigs\n```\n\n## Quick Start\n\nTigs provides two main interactive TUI (Terminal User Interface) commands:\n\nWith Claude Code, run `tigs` inside any directory of a Git repo that has Claude Code sessions.\nAll your chat history associated with the repo will be loaded and ready to store with commits!\n\n### `tigs store` - Select and Store Chats\n\nLaunch an interactive interface to select commits and messages to associate with code commits:\n\n```bash\ntigs store\n```\n\nThe store interface features:\n- **Three-pane layout**: Commits (left), Messages (center), Logs (right)\n- **Keyboard navigation**:\n - `j/k` or `\u2191/\u2193` - Navigate up/down\n - `Space` - Toggle selection\n - `v` - Visual selection mode\n - `a` - Select all\n - `c` - Clear selections\n - `Tab` - Switch between panes\n - `s` - Store selected items as a chat\n - `q` - Quit\n\n### `tigs view` - Browse and Read Chats\n\nExplore existing chats associated with your commits:\n\n```bash\ntigs view\n```\n\nThe view interface displays:\n- **Three-column layout**: Commits list, Commit details, Chat content\n- **Navigation**: Browse through commits and view associated chats\n- **Read-only mode**: Safely explore without modifying data\n\n### Provider discovery\n\nTigs reads chat histories through `cligent` adapters. Out of the box the\nlogs pane surfaces sessions from Claude Code, Gemini CLI, and Qwen Code when\nthose logs exist locally, including nested Claude project folders that match\nthe current directory's prefix.\n\nTo restrict the scan to specific adapters, set the `TIGS_CHAT_PROVIDERS`\nenvironment variable before launching the TUI:\n\n```bash\n# Example: only show Claude Code conversations\nTIGS_CHAT_PROVIDERS=claude-code tigs store\n```\n\nEvery entry in the logs pane includes a provider label so you can quickly\nspot which tool produced a session. Set `TIGS_CHAT_RECURSIVE=0` if you prefer\nto limit discovery to the exact project directory you launched Tigs from.\n\n## Syncing with Remote Repositories\n\nShare your chats across team members using Git-native sync workflow:\n\n```bash\n# Pull (fetch + merge) chats from remote\ntigs pull # Default: union strategy (preserves all conversations)\n\n# Or specify merge strategy\ntigs pull --strategy=ours # Keep local on conflict\ntigs pull --strategy=theirs # Keep remote on conflict\n\n# Push chats to remote repository\ntigs push\n```\n\n### How Sync Works\n\n- **`tigs fetch`**: Downloads remote notes to staging namespace (`refs/notes-remote/<remote>/chats`) - safe, read-only\n- **`tigs pull`**: Fetches and merges using git notes merge strategies\n - `union` (default): Combines all conversations separately, no message mixing\n - `ours`: Keep local notes on conflict\n - `theirs`: Keep remote notes on conflict\n - `manual`: Require manual resolution\n- **`tigs push`**: Uploads your local notes to remote\n\nThe `push` command validates that all commits with chats are pushed to the remote before pushing the notes, preventing orphaned references.\n\n**Multi-user workflow**: Each user's chat is preserved as an independent conversation. The default `union` strategy combines all chats using YAML multi-document format, ensuring no messages are mixed across different conversations.\n\n## Low-Level Commands\n\nFor automation and scripting, Tigs provides direct CLI commands:\n\n```bash\n# Add chat to current commit (HEAD)\ntigs add-chat -m \"Chat content in YAML format\"\n\n# Add chat to specific commit\ntigs add-chat abc123 -m \"Chat content\"\n\n# Show chat for current commit\ntigs show-chat\n\n# Show chat for specific commit\ntigs show-chat abc123\n\n# List all commits that have chats\ntigs list-chats\n\n# Remove chat from commit\ntigs remove-chat abc123\n```\n\n### Interactive Editor\n\nIf you don't provide the `-m` flag, tigs opens your default editor:\n\n```bash\n# Opens editor for chat content\ntigs add-chat\n```\n\n## Chat Format\n\nChats are stored in YAML format following the `tigs.chat/v1` schema:\n\n```yaml\nschema: tigs.chat/v1\nmessages:\n- role: user\n content: What does this commit implement?\n- role: assistant\n content: This commit adds authentication using JWT tokens.\n```\n\n## Git Integration\n\nTigs stores chats as Git notes in `refs/notes/chats`, which means:\n\n- **Version controlled**: Chats are part of Git history\n- **Distributed**: Push/pull chats like any Git data\n- **Non-invasive**: Doesn't modify commits or require rebasing\n- **Compatible**: Works with any Git workflow\n- **Efficient**: Git's fanout structure handles large scale\n\nYou can also use standard Git commands:\n```bash\n# View notes directly\ngit notes --ref=refs/notes/chats show <commit>\n\n# Push notes manually\ngit push origin refs/notes/chats\n```\n\n## Use Cases\n\n- **Code Review**: Attach review discussions with LLM to specific commits\n- **Documentation**: Add design & implementation notes and decisions\n- **Learning**: Annotate commits with explanations for team members\n- **AI Assistance**: Store AI conversations about code changes\n- **Debugging**: Keep notes about bug investigations tied to commits\n\n## Requirements\n\n- Python 3.8+\n- Git 2.17+\n- Terminal with UTF-8 support\n- Unix-like system (Linux, macOS, WSL)\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Talks in Git \u2192 Specs - Git-based chat management system for AI-empowered software development",
"version": "0.1.4",
"project_urls": {
"Discord": "https://discord.gg/8krkc4z5wK",
"Homepage": "https://github.com/sublang-ai/tigs",
"Issues": "https://github.com/sublang-ai/tigs/issues",
"Repository": "https://github.com/sublang-ai/tigs"
},
"split_keywords": [
"ai",
" chat",
" chatgpt",
" claude",
" development-tools",
" gemini",
" git",
" llm",
" prompts",
" qwen",
" software-development",
" spec-driven",
" specifications",
" specs",
" version-control",
" vibe-coding"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fc38d68c5ab2cc722785406539013742d9ad6d1c7ffc4f4aaf84cc66d4535ffb",
"md5": "62a22b2ec40c3ad8a10418b4a1b7b1ff",
"sha256": "94de0d8d3725e49c50d34a793afd01b9d9e4d62943e70858f93eeda931d05fe5"
},
"downloads": -1,
"filename": "tigs-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "62a22b2ec40c3ad8a10418b4a1b7b1ff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 57171,
"upload_time": "2025-10-08T06:24:21",
"upload_time_iso_8601": "2025-10-08T06:24:21.635424Z",
"url": "https://files.pythonhosted.org/packages/fc/38/d68c5ab2cc722785406539013742d9ad6d1c7ffc4f4aaf84cc66d4535ffb/tigs-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e31dfaa4be1189da3cdb0c949633256b2436e043f48b7abb426e57572f6b9388",
"md5": "aada95cf68811a2aa9f72b1d7a89ff2e",
"sha256": "864b4a893faa9c052fe04df0d952b8393582c87e42d3b536fc16af2f25fe39d3"
},
"downloads": -1,
"filename": "tigs-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "aada95cf68811a2aa9f72b1d7a89ff2e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 2688567,
"upload_time": "2025-10-08T06:24:24",
"upload_time_iso_8601": "2025-10-08T06:24:24.744810Z",
"url": "https://files.pythonhosted.org/packages/e3/1d/faa4be1189da3cdb0c949633256b2436e043f48b7abb426e57572f6b9388/tigs-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-08 06:24:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sublang-ai",
"github_project": "tigs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "tigs"
}
JSON
