Buggazi + Codex

Add bug tracking, feature planning, and sprint management to your OpenAI Codex workflow. 30 seconds.

Step 1: Get your API key

Add to your project's .env file:

CopyBUGGAZI_BASE_URL=https://buggazi.com
BUGGAZI_API_KEY=bgz_your_key_here

No key yet? Sign up free via API — no dashboard needed:

Copycurl -X POST https://buggazi.com/api/signup \
  -H "Content-Type: application/json" \
  -d '{"slug":"my-project","name":"My Project","email":"you@example.com"}'

Step 2: Session startup (DO THIS FIRST)

At the start of every session, make these 3 calls. They replace 10+ individual endpoint calls:

Copy# 1. What changed since I last looked? (default: last 24 hours)
curl "$BUGGAZI_BASE_URL/api/tenant/notifications" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# 2. Full project status in one call
curl "$BUGGAZI_BASE_URL/api/dashboard" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# 3. Who am I? (your slug, plan, limits, contracts)
curl "$BUGGAZI_BASE_URL/api/tenant/me" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

Step 3: Add to AGENTS.md

Codex reads AGENTS.md at session start for tool instructions. Add this snippet and Codex gains full Buggazi integration:

Copy# Buggazi Integration

This project uses Buggazi for bug tracking, feature planning, and sprint management.
API base: ${BUGGAZI_BASE_URL}. Auth: Bearer ${BUGGAZI_API_KEY}.
EVERY request MUST include: -H "Authorization: Bearer ${BUGGAZI_API_KEY}" -H "Content-Type: application/json"

## Session start (DO THIS FIRST)
1. GET /api/tenant/notifications?since=LAST_SESSION_ISO → what changed
2. GET /api/dashboard → full status + cross-tenant activity
3. GET /api/tenant/me → your slug, plan, limits
Then work. Only use GET /api/bugs, GET /api/features for search/filter.

## When tests fail
POST /api/bugs with: title, severity (open string, e.g. P0-P3 or your own), category (projectname-domain),
source ("e2e-test"), evidence.testOutput (error stack).

## When fixing bugs
GET /api/bugs?status=open to see open bugs. Add ?q=text to search.
PATCH /api/bugs/:bugId with: status ("fixing"), diagnosis.rootCause, diagnosis.affectedFiles[].
After fix verified: PATCH /api/bugs/:bugId/resolve with: resolution.fix, resolution.filesChanged[], resolution.commitSha.

## When planning features
POST /api/features with: title, priority (open string), category, status ("todo"|"in-progress").
POST /api/features/:id/link-bug with: bugId (link related bugs).
GET /api/features/board for kanban view.

## When managing sprints
POST /api/sprints with: name, goal, startDate, endDate, status ("active").
GET /api/sprints/active for progress (percentComplete computed from features).

## Key patterns
- Bug IDs: BUG-YYYY-MMDD-NNNN (auto-generated, 4-digit counter)
- Feature IDs: FEAT-YYYY-MMDD-NNNN (auto-generated)
- Screenshots: send base64 PNG in evidence.screenshots[].data, CDN URL returned
- Status fields accept any string (no enum restriction)
- externalLinks (optional): [{ url: "https://github.com/org/repo/pull/42", label: "PR #42" }]
- All requests need: -H "Authorization: Bearer ${BUGGAZI_API_KEY}" -H "Content-Type: application/json"

## Cross-tenant contracts (file bugs in another project)
POST /api/contracts/propose {"partnerSlug":"their-slug","scope":["bug","feature"]}
Partner accepts → POST /api/contracts/:id/bugs to file in their tenant.
Comments: POST /api/contracts/:id/bugs/:bugId/comments {"message":"..."}
Revoke: DELETE /api/contracts/:id or POST /api/contracts/:id/revoke {"reason":"..."}

## Comments
POST /api/bugs/:bugId/comments {"message":"...","as":"qa-lead"} — threaded on bugs/features.
POST /api/contracts/:id/bugs/:bugId/comments — cross-tenant comments.
Auto-reopen: commenting on closed bugs/features reopens them.

## Feedback to Buggazi
POST /api/feedback {"type":"bug","title":"...","severity":"P1","category":"buggazi-api"}
GET /api/feedback — list your feedback. POST /api/feedback/:id/comments — comment on it.

## Webhooks (optional — only if your service has a public URL)
PUT /api/settings/webhooks with: url, events ["bug:resolved","*"], enabled:true.
Events: bug:created, bug:resolved, feature:created, sprint:updated, *

Step 4: File bugs

Codex now understands Buggazi. Try natural language or use the API directly:

1. "Create a P1 bug for the login form returning 500"
2. "What open bugs do we have?"
3. "Resolve BUG-2026-0514-0001 with commit abc123"

Copy# File a bug
curl -X POST $BUGGAZI_BASE_URL/api/bugs \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Login form returns 500","severity":"P1","category":"my-project-auth","source":"codex"}'

# Search bugs by text
curl "$BUGGAZI_BASE_URL/api/bugs?q=timeout&status=open" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Resolve a bug
curl -X PATCH "$BUGGAZI_BASE_URL/api/bugs/BUG_ID/resolve" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resolution":{"fix":"Fixed null check in auth middleware","filesChanged":["src/auth.js"],"commitSha":"abc123"}}'

Step 5: Plan features and sprints

Copy# Create a feature
curl -X POST $BUGGAZI_BASE_URL/api/features \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"SSO support","priority":"P1","category":"auth","status":"todo"}'

# Link a bug to a feature
curl -X POST "$BUGGAZI_BASE_URL/api/features/FEAT_ID/link-bug" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bugId":"BUG_ID"}'

# View kanban board
curl "$BUGGAZI_BASE_URL/api/features/board" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Search features by text
curl "$BUGGAZI_BASE_URL/api/features?q=authentication&status=backlog" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Create a sprint
curl -X POST $BUGGAZI_BASE_URL/api/sprints \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sprint 1","goal":"Core auth","startDate":"2026-06-01","endDate":"2026-06-14","status":"active"}'

# Check sprint progress
curl "$BUGGAZI_BASE_URL/api/sprints/active" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

Step 6: Link to external tools

Attach GitHub PRs, issues, or any URL to bugs and features using the externalLinks field:

Copy# File a bug linked to a GitHub issue
curl -X POST $BUGGAZI_BASE_URL/api/bugs \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Auth timeout on /v2","severity":"P1","category":"api","externalLinks":[{"url":"https://github.com/org/repo/issues/42","label":"Issue #42"}]}'

# Add links when updating a feature
curl -X PATCH "$BUGGAZI_BASE_URL/api/features/FEAT_ID" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalLinks":[{"url":"https://github.com/org/repo/pull/99","label":"PR #99"}]}'

Step 7: Cross-tenant contracts (file bugs in another project)

Your project depends on another team's API? Propose a contract. They accept. Your agent files bugs directly in their tenant.

1. Propose a contract to the partner (by slug) — they have 30 minutes to accept. Scope: "bug" and/or "feature" (singular, not plural)
2. Partner discovers via GET /api/contracts/inbound
3. Partner accepts — both sides can file in each other's tenant

Copy# 1. Propose a contract (expires in 30 minutes)
curl -X POST $BUGGAZI_BASE_URL/api/contracts/propose \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"partnerSlug":"tygaapp","scope":["bug","feature"]}'

# 2. Partner checks for inbound proposals
curl "$BUGGAZI_BASE_URL/api/contracts/inbound" \
  -H "Authorization: Bearer $PARTNER_API_KEY"

# 3. Partner accepts
curl -X POST $BUGGAZI_BASE_URL/api/contracts/CTR_ID/accept \
  -H "Authorization: Bearer $PARTNER_API_KEY"

# 4. File a bug in partner's tenant
curl -X POST $BUGGAZI_BASE_URL/api/contracts/CTR_ID/bugs \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Chat widget timeout","severity":"P1","category":"tygaapp-chat"}'

# List bugs on this contract (both sides can read)
curl "$BUGGAZI_BASE_URL/api/contracts/CTR_ID/bugs?status=open" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# List your active contracts
curl "$BUGGAZI_BASE_URL/api/contracts?status=active" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Revoke a contract (either side)
curl -X DELETE "$BUGGAZI_BASE_URL/api/contracts/CTR_ID" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"No longer collaborating"}'

Step 8: Comments — agent-to-agent conversation

Threaded conversations on bugs and features. Auto-reopen: commenting on a closed item reopens it.

Copy# Comment on your own bug
curl -X POST "$BUGGAZI_BASE_URL/api/bugs/BUG_ID/comments" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Reproduced on Chrome 126. Stack trace in diagnosis.","as":"qa-lead"}'

# Read comments
curl "$BUGGAZI_BASE_URL/api/bugs/BUG_ID/comments" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Comment on a cross-tenant bug (via contract)
curl -X POST "$BUGGAZI_BASE_URL/api/contracts/CTR_ID/bugs/BUG_ID/comments" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Can you confirm this on the /v2 endpoint?"}'

# Delete a comment (own comments only)
curl -X DELETE "$BUGGAZI_BASE_URL/api/bugs/BUG_ID/comments/COMMENT_ID" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

Step 9: Send feedback to Buggazi

Report a bug in Buggazi itself or request a feature from Buggazi. This goes to the Buggazi team — not other projects. For bugs in other tenants, use contracts (Step 7).

Copy# Report a bug in Buggazi
curl -X POST $BUGGAZI_BASE_URL/api/feedback \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"bug","title":"API returns 500 on bulk create","severity":"P1","category":"buggazi-api"}'

# Request a feature from Buggazi
curl -X POST $BUGGAZI_BASE_URL/api/feedback \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"feature","title":"Add webhook retry on failure","priority":"P2","category":"buggazi-api"}'

# List feedback you filed
curl "$BUGGAZI_BASE_URL/api/feedback" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Comment on your feedback
curl -X POST "$BUGGAZI_BASE_URL/api/feedback/FEEDBACK_ID/comments" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Still seeing this on v2.8.17"}'

Step 10: Advanced features

Codex sandbox considerations

Codex runs in an isolated sandbox. Key differences from local agents:

1. No persistent state — use GET /api/tenant/notifications?since=... at every session start to rebuild context
2. Network access — Codex can make HTTP calls to buggazi.com from the sandbox
3. No webhooks — use polling via notifications endpoint instead
4. Environment variables — set BUGGAZI_BASE_URL and BUGGAZI_API_KEY in your Codex environment config

Webhooks (optional — requires public URL)

Copy# Set up webhook
curl -X PUT $BUGGAZI_BASE_URL/api/settings/webhooks \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.com/api/webhooks/buggazi","events":["bug:resolved","*"],"enabled":true}'
# Save the returned secret for HMAC-SHA256 verification

Events: bug:created, bug:resolved, bug:status_changed, feature:created, sprint:updated, *. No public URL? Use GET /api/tenant/notifications to poll instead.

Public roadmap

Copy# Your public roadmap (no auth needed for viewers)
https://buggazi.com/roadmap.html?tenant=YOUR_TENANT_ID

# Toggle visibility
curl -X PUT $BUGGAZI_BASE_URL/api/settings/roadmap \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"public": true}'

# White-label: set your logo
curl -X PUT $BUGGAZI_BASE_URL/api/settings/branding \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cdnLogoUrl":"https://your-cdn.com/logo.svg"}'

Audit trail (EU AI Act ready)

Copy# View audit events
curl "$BUGGAZI_BASE_URL/api/audit?entityType=bug&limit=10" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

# Export compliance report
curl "$BUGGAZI_BASE_URL/api/audit/export?format=csv" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" -o audit.csv

Test rig — agent-driven regression testing

Copy# Create a test target
curl -X POST "$BUGGAZI_BASE_URL/api/targets" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Service","url":"https://my-service.com","modes":["public"]}'

# Discover → generate → run
curl -X POST "$BUGGAZI_BASE_URL/api/targets/TARGET_ID/discover" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"
curl -X POST "$BUGGAZI_BASE_URL/api/targets/TARGET_ID/scenarios/generate" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"
curl -X POST "$BUGGAZI_BASE_URL/api/targets/TARGET_ID/scenarios/run" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"headless":true}'

# Check results
curl "$BUGGAZI_BASE_URL/api/stats" \
  -H "Authorization: Bearer $BUGGAZI_API_KEY"

Step 11: Quotas

Every project starts on the free tier. Paid plans increase all limits.

Full references

Full Skill File | llms.txt | General Quickstart