dave-tools

A personal toolbox for AI-assisted software development: CLI utilities for automating everyday git/PR/repo chores, a reusable library of coding-agent components (commands, skills, agents), and a framework for running coding agents unattended against task specifications.

Works with three coding agents: Claude Code, OpenCode, Codex CLI, and GitHub Copilot.

Requirements

• Linux or macOS
• uv — runs the Python scripts (Python 3.13+)
• Task — task runner used for install/update
• git, curl
• Optional, per feature:
  • At least one coding agent CLI (claude, opencode, codex, or GitHub Copilot) for the agent-driven tools
  • gh, tea, or glab for PR automation on GitHub / Gitea / GitLab
  • Node.js 20.19+ and npm for OpenSpec

Installation

git clone <this-repo> && cd dave-tools
task install

task install does three things:

1. Agent config — copies the components from agent-config/ into the global config of all supported agents:
   • Claude Code: ~/.claude/{commands,agents,skills}/
   • OpenCode: ~/.config/opencode/{commands,agents,skills}/
   • Codex CLI: ~/.codex/prompts/ (commands, flattened) and ~/.agents/skills/ (skills)
   • GitHub Copilot: ~/.copilot/skills/ (skills only — Copilot-native path, avoids duplication)
2. Python CLIs — creates dave-* wrapper scripts in ~/.local/bin/
3. Shell scripts — copies the scripts from scripts/ to ~/.local/bin/

Components are copied, not symlinked — re-run task install after pulling updates.

To install or update the agent CLIs themselves (Claude Code, OpenCode, Codex CLI, OpenSpec, Spec Kit, RTK), plus pre-commit hooks:

task update

CLI tools

Installed to ~/.local/bin by task install:

Command	What it does
dave-pr	Full PR workflow: lint, push, create PR, wait for CI, optionally merge. Supports GitHub, Gitea, and GitLab with auto-detection from the git remote. See docs/auto-pr.md.
dave-implement-all-phases	Fully unattended implementation of all incomplete phases from a Spec Kit tasks.md (see below).
dave-bootstrap-repo	Initialize a new Python repo: template files, Spec Kit, agent init (/init), remote creation and push.
dave-gitlab-sync	Clone all repositories in a GitLab group (including subgroups) and pull changes in already-cloned ones. See docs/infra-map.md.
dave-infra-scan	Scan a directory tree of git repos for infrastructure-as-code and collect infra-resources.md files into a central registry. See docs/infra-map.md.
dave-infra-compose	Compose a cross-repo infrastructure map (Markdown, graph JSON, Mermaid diagram, interactive HTML) from the registry. See docs/infra-map.md.
dave-infra-refresh	Full refresh in one command: sync GitLab repos, scan for IaC, compose the map. Suitable for cron / CI scheduling. See docs/infra-map.md.
dave-fetch-lint-rule-docs	Fetch and locally cache Ruff / ShellCheck rule documentation (--ruff-rule TRY301, --shellcheck-rule SC2086).
dave-shift-commit-timestamps	Shift git commit author/committer timestamps by an offset (e.g. -8h, +1d) using git-filter-repo.
claude-bedrock	Run Claude Code against AWS Bedrock (eu-central-1).

All Python tools can also be run from the repo without installing: uv run src/<script>.py --help.

Choosing a coding agent

The agent-driven tools (dave-implement-all-phases, dave-infra-scan, dave-infra-compose, dave-bootstrap-repo) accept --agent-type claude|opencode|codex (default: claude) and --agent-executable to point at a specific binary.

They also accept --approval-mode:

Mode	Behavior
use-permissions	Normal permission prompts (default for implement)
skip-permissions	Bypass permission checks (default for infra scan/compose)
full-auto	Like skip-permissions, plus the agent exits automatically when done — for unattended runs

Agent configuration library

agent-config/ is a collection of reusable components installed globally for all three agents:

• Commands (slash commands): /brainstorm, /review, /fix-all-lint-issues, /simplify-code, /summarize-changes, /write-mr-description, /push-fix-pr, /improve-docs, /scan-pii, /infra-scan, /setup-devcontainer, /setup-pre-commit, /setup-renovate, /debug-kubernetes (with subcommands), /network-recon (with subcommands)
• Skills: automation-audit, brainstorm, duckdb, gitlab-cicd, improve-agent-skills, infra-query, proxmox-ve, review-branch, skill-creator, systematic-debugging, taskfile, wrap-up-self-improve
• Agents: code-simplifier (Claude Code / OpenCode only)

Notes for Codex CLI: commands are installed as custom prompts in ~/.codex/prompts/, with nested subcommands flattened (e.g. /debug-kubernetes:networking becomes /debug-kubernetes-networking); skills use the same SKILL.md format across all agents and are installed to ~/.agents/skills/.

Notes for GitHub Copilot: skills are installed to ~/.copilot/skills/ (the Copilot-native personal skills path). This avoids duplication — Copilot also scans ~/.claude/skills/ and ~/.agents/skills/ but does not deduplicate by name across those paths.

Phase-based implementation workflow

dave-implement-all-phases (or uv run src/implement-next-phase.py) drives a coding agent through a Spec Kit task list:

1. Reads phases from specs/NNN-feature-name/tasks.md (matched to the current branch prefix, or overridden with the SPECIFY_FEATURE environment variable)
2. Runs the agent with /speckit.implement for the next incomplete phase
3. Runs pre-commit hooks and has the agent fix lint issues (/fix-lint-issues)
4. Commits with the message Implement <phase>
5. Repeats for the next phase (--all-phases)

It retries failed steps with backoff and recovers from interrupted runs (an implemented but uncommitted phase is committed instead of re-implemented).

# Implement just the next incomplete phase, with permission prompts
uv run src/implement-next-phase.py

# Everything, unattended
dave-implement-all-phases

# Same, but with a different agent
uv run src/implement-next-phase.py --all-phases --approval-mode full-auto --agent-type codex

Bootstrapping a new repository

dave-bootstrap-repo /path/to/new-repo

Initializes git, copies a Python project template (TEMPLATE_PATH in .env or --template-path), sets up Spec Kit, runs the agent's /init to generate project instructions, and creates + pushes a private remote. Each step can be disabled (--no-add-template, --no-add-spec-kit, --no-run-agent-init, --no-create-remote). Use --agent-type claudecode|opencode|codex (repeatable) to choose which agents to set up.

Documentation

• docs/auto-pr.md — PR automation: subcommands, platform support matrix, examples
• docs/infra-map.md — cross-repo infrastructure mapping: scan, compose, query
• CLAUDE.md — architecture notes and contributor guidance (aimed at coding agents)

Development

uv sync        # set up the environment
task lint      # pre-commit on all files
task test      # pytest (unit + e2e)
task build     # lint + test

Repository layout: Python sources in src/ (shared code under src/utils/), tests in tests/unit/ and tests/e2e/, shell scripts in scripts/, agent components in agent-config/.