Dingles

A simple, git-backed issue tracker for AI coding agents.

Dingles stores issues as JSON files in your git repository, making it easy for AI agents to create, track, and manage tasks without losing context between sessions.

Features

• Git-native: Issues stored in .dingles/issues/, synced via git
• Two modes: Branch mode (separate issues branch) or JSONL mode (same branch as code)
• Simple: Pure Go, no external dependencies (no database server required)
• Dependency tracking: Issues can depend on other issues
• AI-friendly: Machine-readable JSON output, easy to script
• Flexible: Multiple output formats, verbose modes for debugging

Installation

# Build from source
git clone https://codeberg.org/mutablecc/dingles.git
cd dingles
make build
# Or install to ~/.local/bin
make install

Quick Start

# Initialize in your project
dingles init --agents
# Create an issue
dingles create "Build user authentication"
# List all issues
dingles list
# Find ready-to-work issues (no blockers)
dingles ready
# Close an issue
dingles close ding-abc123 --reason "Implemented"

Commands

Common Options

Global Options

• --help - Show help
• --verbose - Show verbose messages
• --debug - Show debug messages
• --no-git - Disable git integration

Init Options

dingles init [options]
Options:
 --agents Create or update AGENTS.md with dingles instructions for AI agents

Create Options

dingles create [options] <title>
Options:
 --description string Issue description
 --type string Issue type: task, bug, epic (default: task)
 --priority int Priority 0-4, lower is higher (default: 1)
 --assignee string Assignee name
 --parent string Parent issue ID
 --depends-on string Comma-separated dependency IDs
 --tags string Comma-separated tags
 --commit Auto-commit changes

List Options

dingles list [options]
Options:
 --status string Filter: open, in_progress, closed
 --type string Filter: task, bug, epic
 --format string Output: table, json (default: table)

Update Options

dingles update [options] <issue-id>
Options:
 --title string New title
 --description string New description
 --assignee string New assignee
 --priority int New priority (0-4)
 --status int New status (0=open, 1=in_progress, 2=closed)
 --type string New issue type (task, bug, epic)
 --parent string New parent issue ID
 --depends-on string Comma-separated dependency IDs
 --comment string Add a progress comment
 --comment-file string Read comment from a file
 --author string Comment author (defaults to $USER)
 --commit Auto-commit changes
 --force Force operation (override conflicts)
 --edit Open editor to edit full issue

Close Options

dingles close [options] <issue-id>
Options:
 --reason string Reason for closing
 --commit Auto-commit changes

Examples

Create Issues with Dependencies

# Create a parent epic
dingles create --priority 0 --type epic "Build new API"
# Create child tasks
dingles create "Design API endpoints"
dingles create "Implement API endpoints"
# Add dependencies (child depends on parent)
EPIC=$(dingles list --format json | jq -r '.[0].id')
TASK=$(dingles list --format json | jq -r '.[1].id')
dingles dep add $TASK $EPIC

AI Agent Workflow

# Start new session - find ready work
dingles ready
# Claim an issue
dingles claim ding-abc123
# Do the work...
# Update with progress comments
dingles update --comment "Found root cause in auth.go:42" ding-abc123
dingles update --comment "Fixed by adding input validation" ding-abc123
# Close when done
dingles close ding-abc123 --reason "Implemented feature X"

Filter and Format

# List only open bugs
dingles list --type bug --status open
# Get JSON for scripting
dingles list --format json
# Show verbose output
dingles --verbose list

File Structure

.
├── .dingles/
│ ├── config.json # Configuration (mode, issues_branch, auto_sync)
│ ├── issues/ # Issue JSON files (used by both modes)
│ ├── events.jsonl # Event log (JSONL mode only)
│ └── hooks/ # Git hook scripts
├── .dingles-hooks/ # Shared hooks (if using --shared)
└── .git/ # Git repository

In branch mode (default), issues are synced to the issues branch. In JSONL mode, issues are committed to the same branch as code.

Git Integration

Dingles automatically detects the git repository root and stores issues based on the configured mode.

For branch mode, issues are synced to the issues branch:

# Sync changes to issues branch
dingles create --sync "New issue"
dingles close ding-abc123 --reason "Done" --sync
# Or manually
git add .dingles/issues/
git commit -m "Update issues"
git push origin issues

For JSONL mode, issues are committed to the same branch:

git add .dingles/events.jsonl
git commit -m "dingles: update issues"
git push

AI Agent Setup

When you run dingles init --agents, it creates or updates an AGENTS.md file in your project with instructions for AI agents. This tells AI coding agents (like Claude Code, Copilot, etc.) to use dingles for task tracking instead of markdown TODO lists.

dingles init --agents

The generated AGENTS.md includes:

• How to use dingles commands
• Issue types and priorities
• Workflow instructions for AI agents
• Important rules (use dingles, not TODOs)

Sync Flags

• --commit: Auto-commit changes to local git
• --sync: Auto-commit and push to issues branch

dingles create --sync "New issue"
dingles close ding-abc123 --reason "Done" --sync

Progress Comments

# Add a comment with findings
dingles update --comment "Root cause is a race condition in worker.go" ding-abc123
# Add a comment from a file (for longer notes)
dingles update --comment-file findings.txt ding-abc123
# Update status AND add a comment atomically
dingles update --status 1 --comment "Starting implementation" ding-abc123
# AI agents should identify themselves
dingles update --author ai --comment "Analyzed the call stack, issue is in parser.go:42" ding-abc123
### Sharing Issues
Issues sync via git like any code:
```bash
# After pulling changes
git pull
# Your local issues are automatically updated
dingles list

Git Hooks

Dingles includes git hooks to ensure issues stay synced with your commits and pushes:

• pre-commit: Flushes pending changes before commit
• pre-push: Blocks push if there are uncommitted dingles changes
• post-merge: Syncs issues after git pull/merge

Install Hooks

# Install hooks to .git/hooks/ (local only)
dingles hooks
# Install to .dingles-hooks/ and configure git hooksPath (for teams)
dingles hooks --shared

The --shared option is useful for teams because the hooks are stored in .dingles-hooks/ which can be committed to the repository, ensuring all team members have the same hooks.

Hook Behavior

Hooks are mode-aware and check config.json to determine behavior:

• pre-commit: When auto_sync: true, auto-commits changes to issues
• pre-push: Checks for uncommitted changes in .dingles/issues/ (branch mode) or .dingles/events.jsonl (JSONL mode)
• post-merge: When auto_sync: true, pulls latest from issues branch

Environment Variables

• DINGLES_DIR - Override the .dingles directory location
• USER - Used as default assignee for claim command

Configuration

Dingles stores configuration in .dingles/config.json:

{
 "mode": "branch",
 "issues_branch": "issues",
 "auto_sync": false
}

Config Options

Storage Modes

Branch Mode (default): Issues stored in .dingles/issues/*.json, synced to a dedicated issues branch. Clean separation between code and issues.

JSONL Mode: Issues stored in .dingles/events.jsonl as an append-only event log, committed to the same branch as code. Full audit trail of changes.

See DESIGN.md for detailed comparison.

Sync Behavior

By default (auto_sync: false), changes are local. Use --sync flag to commit and push:

dingles create "New issue" --sync
dingles close ding-abc123 --reason "Done" --sync

Without --sync, a warning is shown if local changes exist.

Exit Codes

• 0 - Success
• 1 - Error

Help

# Global help
dingles --help
# Command help
dingles create --help
dingles list --help
# Verbose output for debugging
dingles --verbose <command>
dingles --debug <command>

Design

See DESIGN.md for technical details.

License

MIT