All topics

Using Yoke from Claude Code

Yoke's API is designed for AI agents: scoped tokens, self-describing errors, a discovery endpoint, and an audit log of everything the agent did. That makes it a natural task board for Claude Code — your agent can file follow-ups, track its own work, and report progress where you'll actually see it.

Setup

  1. Create a write-scope token on Workspace → API tokens (one token per agent — see API tokens).
  2. Give Claude Code the token and base URL, e.g. as environment variables in your shell or project:
export YOKE_API_URL="https://<deployment>.convex.site"
export YOKE_API_TOKEN="yk_..."
  1. Tell the agent how to use it — a short note in your project's CLAUDE.md (or a custom skill) is enough:
## Task tracking
We track work in Yoke. Use its REST API with $YOKE_API_TOKEN:
- GET  $YOKE_API_URL/api/app/meta            — projects/labels/statuses (ids)
- GET  $YOKE_API_URL/api/app/tasks           — list open tasks
- POST $YOKE_API_URL/api/app/tasks           — create ({title, priority, ...})
- PATCH $YOKE_API_URL/api/app/tasks/:id      — update; {"status": "Done"} completes
- POST $YOKE_API_URL/api/app/tasks/:id/comments — progress notes
Auth: Authorization: Bearer $YOKE_API_TOKEN. Full docs: /help/api-reference.

What this looks like in practice

  • "File a Yoke task for every TODO you find in this codebase" — the agent calls /meta to find the right project, then creates prioritised tasks.
  • "Work through my 'Refactor' project" — it lists the tasks, moves each to In progress, comments with what it did, and moves it to Done.
  • A read-only token is enough for standup-style reporting: "summarise what's still open and overdue".

Guardrails

The token's scope is the hard boundary — a read token can't write, whatever the prompt says. Rate limiting (120 req/min) keeps a runaway loop from flooding the board, and the audit log on the tokens page shows every request the agent made, with method, path and status.