agent-tools

---
name: agent-tools
description: LOAD THIS SKILL when: using CLI wrapper tools (gh-tool, observability-tool, db-tool, k8s-tool, az-tool, azdo-tool, logs-tool, session-tool), working with observability, databases, GitHub PRs, Kubernetes, Azure platform resources, Azure DevOps, or application logs. Contains tool overview, usage patterns, and project-specific aliases.
license: MIT
---

# Agent Tools

Safe CLI wrappers for AI coding agents — GitHub, observability, databases, Kubernetes, Azure platform, Azure DevOps, logs, and OpenCode sessions.

**Full documentation**: Read the [README](https://github.com/blogic-cz/agent-tools) for complete API reference, configuration, and credential setup.

## How to Run (CRITICAL)

Run tools via `bun <tool-name>` (requires `@blogic-cz/agent-tools` as a dev dependency):

```bash
bun gh-tool pr status
bun observability-tool trace get <trace-id> --env local
bun k8s-tool pods --env test
bun db-tool sql --env local --sql "SELECT 1"
```

**NEVER run raw `kubectl`, `gh`, `psql`, `az`** — the credential guard will block them.

Legacy `agent-tools-*` binary names (e.g. `bun gh-tool`) still work but prefer the short form.

## Tools Overview

| Tool                   | Description                                                         | Help                            |
| ---------------------- | ------------------------------------------------------------------- | ------------------------------- |
| **gh-tool**            | GitHub CLI wrapper — PRs, issues, workflows, checks, reviews, merge | `bun gh-tool --help`            |
| **observability-tool** | LGTM wrapper — Tempo traces, Loki logs, Prometheus metrics          | `bun observability-tool --help` |
| **db-tool**            | Database query tool — SQL execution, schema introspection           | `bun db-tool --help`            |
| **k8s-tool**           | Kubernetes tool — kubectl with config-driven context resolution     | `bun k8s-tool --help`           |
| **az-tool**            | Azure platform tool — vm, webapp, storage, aks, acr (read-only)     | `bun az-tool --help`            |
| **azdo-tool**          | Azure DevOps tool — pipelines, builds, repos (read-only)            | `bun azdo-tool --help`          |
| **logs-tool**          | Application logs — read local and remote (k8s pod) logs             | `bun logs-tool --help`          |
| **session-tool**       | OpenCode session browser — list, read, search session history       | `bun session-tool --help`       |

## Tool Priority

1. **CLI Tools (Preferred)** — More efficient, don't load context, provide full functionality
2. **MCP Tools (Fallback)** — Use when CLI alternatives don't exist

Always prefer `bun gh-tool` over raw `gh`, `bun db-tool` over raw `psql`, `bun k8s-tool` over raw `kubectl`. The wrappers add security guardrails, audit trails, and project-specific config.

**Consistency**: Tools provide `hint`, `nextCommand`, and `retryable` fields in error responses to help you recover from failures. Always check these fields when a command fails.

## Quick Reference

### gh-tool (GitHub)

```bash
bun gh-tool pr status                  # View PR status for current branch
bun gh-tool pr view --pr 123           # View PR details
bun gh-tool pr checks --pr 123         # Check CI status
bun gh-tool pr checks --pr 123 --watch # Watch CI until complete
bun gh-tool pr checks-failed --pr 123  # Get failed check details
bun gh-tool pr merge --pr 123 --strategy squash --delete-branch --confirm
bun gh-tool pr threads --pr 123 --unresolved-only  # Review comments
bun gh-tool pr reply --pr 123 --comment-id 456 --body "Fixed"
bun gh-tool pr resolve --thread-id 789
bun gh-tool pr create --base test --title "feat: X" --body "Description"
bun gh-tool pr review-triage --pr 123  # Combined info, threads, checks
bun gh-tool pr reply-and-resolve --pr 123 --comment-id 456 --thread-id 789 --body "Done"
```

```bash
bun gh-tool workflow list                              # List recent workflow runs
bun gh-tool workflow view --run 123                    # View run details with jobs/steps
bun gh-tool workflow watch --run 123                   # Block until run completes (NO sleep-polling!)
bun gh-tool workflow logs --run 123                    # Fetch logs (failed jobs by default)
bun gh-tool workflow job-logs --run 123 --job "build"  # Clean parsed logs for specific job
bun gh-tool workflow rerun --run 123                   # Rerun failed jobs
bun gh-tool workflow cancel --run 123                  # Cancel in-progress run
```

**NEVER use `sleep N && workflow list/jobs/view`** — use `workflow watch --run N` instead. The credential guard blocks sleep-polling with agent-tools commands.

```bash
bun gh-tool issue list --state open --limit 30
bun gh-tool issue view --issue 123
bun gh-tool issue close --issue 123 --reason completed --comment "Done"
bun gh-tool issue reopen --issue 123
bun gh-tool issue comment --issue 123 --body "text"
bun gh-tool issue edit --issue 123 --title "New title" --add-labels bug
bun gh-tool issue triage --issue 123 --verbosity full --format json
```

### observability-tool (LGTM)

```bash
bun observability-tool trace get 0b7bdf0dde1c55458364ba5588a8075e --env local
bun observability-tool trace logs 0b7bdf0dde1c55458364ba5588a8075e --env local --limit 100
bun observability-tool metrics query 'up' --env local --start now-1h --end now --step 60
```

### db-tool (Database)

```bash
bun db-tool sql --env local --sql "SELECT * FROM users LIMIT 5"
bun db-tool sql --env test --sql "SELECT count(*) FROM organizations"
bun db-tool schema --env local --mode tables          # List tables
bun db-tool schema --env local --mode columns --table users # Show table schema
```

Environment is any string (e.g. `local`, `test`, `prod`). Set `defaultEnvironment` in config to skip `--env` on every call.

Database prerequisites may be profile-level (`database.default.vpn`) or environment-level (`database.default.environments.prod.vpn`). Environment `vpn`/`prerequisites` replace profile prerequisites; `prerequisites: []` disables inheritance. DB commands try direct access before connecting VPN prerequisites.

### k8s-tool (Kubernetes)

```bash
bun k8s-tool kubectl --env test --cmd "get pods -n test-ns"
bun k8s-tool kubectl --env prod --cmd "logs <pod> --tail=100"
bun k8s-tool kubectl --env test --cmd "describe pod <pod>"
bun k8s-tool pods --env test                     # List pods
bun k8s-tool logs --pod <pod> --env test --tail 50 # Fetch logs
bun k8s-tool describe --resource pod --name <pod> --env test
bun k8s-tool exec --pod <pod> --exec-cmd "ls -la" --env test
bun k8s-tool top --env test                      # Show resource usage
```

### az-tool (Azure Platform)

```bash
bun az-tool subscription                       # Which subscription am I pinned to?
bun az-tool groups                             # List resource groups
bun az-tool resources --group my-rg            # List resources in a group
bun az-tool cmd --cmd "vm list"
bun az-tool cmd --cmd "webapp show --name my-app --resource-group my-rg"
bun az-tool cmd --cmd "acr repository list --name my-registry"
```

Read-only. The subscription is pinned by the `azurePlatform` config profile —
`--subscription` is rejected. Mutating verbs, unknown verbs, credential reads
(`keyvault secret show`, `storage account keys list`, `get-access-token`), and
shell syntax are all blocked; metadata reads such as `keyvault secret list` stay
allowed. Profiles keyed `prod`/`production` require `--profile` to be passed
explicitly. Load the `az-tool` skill for the full safety model.

### azdo-tool (Azure DevOps)

```bash
bun azdo-tool cmd --cmd "pipelines list"
bun azdo-tool cmd --cmd "pipelines show --id 123"
bun azdo-tool cmd --cmd "pipelines runs list --top 5"
bun azdo-tool cmd --cmd "pipelines runs show --id 456"
bun azdo-tool build summary --build-id 456      # Job status & duration
bun azdo-tool build timeline --build-id 456     # Full event timeline
bun azdo-tool build failed-jobs --build-id 456   # Just failures
bun azdo-tool build logs --build-id 456          # List available logs
bun azdo-tool build log-content --build-id 456 --log-id 78
```

### logs-tool (Application Logs)

```bash
bun logs-tool list --env local          # List available log files
bun logs-tool read --env local --file app.log  # Read specific log
bun logs-tool read --env test --file app.log --tail 50
```

### session-tool (OpenCode Sessions)

```bash
bun session-tool list                   # List recent sessions
bun session-tool read --session <session-id> # Read session messages
bun session-tool search "query"         # Search across sessions
```

## Configuration

Config is loaded from `agent-tools.json5` (or `agent-tools.json`) by walking up from the current working directory.

See full config reference: https://github.com/blogic-cz/agent-tools#configuration

#### defaultEnvironment

Set `defaultEnvironment: "test"` in the root of your config to skip `--env test` in every command. Tools will fail explicitly if they detect an implicit `prod` access for safety.

## Credential Guard

The guard blocks agents from accessing sensitive files and leaking secrets. It's configured via the `credentialGuard` section in `agent-tools.json5`.

**What it blocks:**

- Reads of secret files (`.env`, `.pem`, `.key`, `.ssh/`, etc.)
- Writes containing detected secrets (API keys, tokens, passwords)
- Dangerous shell patterns (`printenv`, `cat .env`, etc.)
- Direct CLI usage (`gh`, `kubectl`, `psql`, `az`) — must use wrapper tools

## Authentication

Each tool uses its own auth — no unified token store:

| Tool                 | Auth                                                           |
| -------------------- | -------------------------------------------------------------- |
| `gh-tool`            | `gh auth login` or `GITHUB_TOKEN` env var                      |
| `observability-tool` | Grafana URL from config plus optional token from `tokenEnvVar` |
| `k8s-tool`           | Existing kubectl context (kubeconfig)                          |
| `az-tool`            | `az login` session                                             |
| `azdo-tool`          | `az login` session                                             |
| `db-tool`            | Env var defined by `passwordEnvVar` in config                  |
| `logs-tool`          | No auth — local files or via k8s-tool for remote access        |