# Guidon

> Guidon is context-first project management for development teams: a Kanban task board per project, plus the decisions, sources, technologies and project memory behind the work. AI agents can pick up tasks, read their full context, report progress and hand finished work back for human review - and keep the project's decisions, knowledge, roadmap and memory up to date - through an MCP server and a REST API.

Guidon is a web app at https://useguidon.com (it can also be self-hosted - source and guide: https://github.com/two-steps-studio/guidon). Everything is organised as organizations -> projects -> tasks. Tasks move through the board columns `backlog`, `todo`, `in_progress`, `ai_working`, `review` and `done`; projects can rename or hide columns.

## When to use Guidon

Use Guidon when an agent should:

- Find the next task to work on in a team's project and claim it, so humans see the agent is on it (`start_task` moves it to the AI-working column).
- Get everything needed to do a task in one call: description, project constraints, verified facts, related decisions, files, pull requests and previous attempts (`get_task_context`).
- Report what it did: comment on the task with a summary and PR link, record failed or partial attempts with the reason, and move the task to `review` for a human to check.
- Create follow-up tasks or subtasks it discovers while working.

Don't use Guidon for general note-taking, chat, or as a code host - it tracks the work and its context, the code lives in your Git host.

## How to connect

Every request carries `Authorization: Bearer <token>`; the token acts as a Guidon user, limited to the projects they can access and to its scopes. Two ways to get one:

1. **OAuth 2.1** (MCP clients such as Claude, ChatGPT, Cursor, VS Code): point the client at `https://useguidon.com/api/mcp`. The `401` carries `WWW-Authenticate: Bearer resource_metadata=...`; the authorization server metadata is at https://useguidon.com/.well-known/oauth-authorization-server (PKCE S256, Client ID Metadata Documents or dynamic registration, refresh tokens). The user approves the app once in their browser. Full walkthrough: [auth.md](https://useguidon.com/auth.md).
2. **API key**: the user creates one in their profile (https://useguidon.com/profile). Keys look like `guidon_...`.

### MCP server (recommended for agents)

- Endpoint: `https://useguidon.com/api/mcp` (MCP Streamable HTTP transport).
- Claude (web/desktop/mobile) and ChatGPT: add a custom connector with the URL `https://useguidon.com/api/mcp` and sign in (OAuth) - no key needed.
- Claude Code: `claude mcp add --transport http guidon https://useguidon.com/api/mcp` (signs in with OAuth), or with a key: `--header "Authorization: Bearer guidon_..."`
- Tools: `list_projects`, `list_tasks`, `list_columns`, `list_priorities`, `get_task`, `get_task_context`, `create_task`, `update_task`, `delete_task`, `start_task`, `set_task_status`, `complete_task`, `comment_on_task`, `list_attempts`, `record_attempt`; and for the rest of the project `list_decisions`, `create_decision`, `list_knowledge_sources`, `list_roadmap_phases`, `update_roadmap_phase`, `list_memories`, `create_memory`, `list_technologies` (plus get/update/delete of each) - with the `project:read`/`project:write` scopes.
- Typical flow: `list_projects` -> `list_tasks` -> `get_task_context` -> `start_task` -> do the work -> `comment_on_task` -> `set_task_status` with `review`.
- `complete_task` (straight to Done) only works when the project allows AI auto-complete; prefer `review`.

### REST API

Base URL `https://useguidon.com/api/v1`, JSON in and out, same bearer key. Full description: [OpenAPI 3.1](https://useguidon.com/openapi.json); API catalog (RFC 9727): [/.well-known/api-catalog](https://useguidon.com/.well-known/api-catalog). Errors are JSON `{ "error": "...", "code": "not_found", "hint": "..." }` with the HTTP status - branch on `code`. Rate limit 60 requests/minute per key (`RateLimit-*` headers, `Retry-After` on 429). Send `Idempotency-Key` on writes so retries never duplicate. `GET .../tasks` pages with `limit`/`cursor` -> `next_cursor`. `POST /batch` runs up to 20 operations at once.

- `GET /projects` - projects the key's user belongs to
- `GET|POST /projects/{projectId}/tasks` - list or create tasks
- `GET /projects/{projectId}/columns` - the project's visible board columns
- `GET|PATCH|DELETE /tasks/{taskId}` - read, edit or delete a task
- `GET /tasks/{taskId}/context` - the task's full working context as Markdown
- `POST /tasks/{taskId}/start` - claim a task
- `PATCH /tasks/{taskId}/status` - move a task to another column
- `POST /tasks/{taskId}/complete` - mark done (if the project allows it)
- `GET|POST /tasks/{taskId}/comment` - read or post task comments
- `GET|POST /tasks/{taskId}/attempts` - list or record attempts
- `POST /batch` - up to 20 of these operations in one request
- `POST /projects/{projectId}/tasks/import` - up to 500 tasks asynchronously: 202 + `Location` of a job to poll at `GET /jobs/{jobId}`
- `POST /sandbox` - a test organization and project of your own with example tasks (`{"reset": true}` resets it): try things there before touching real work

## Docs

- [Developer guide](https://useguidon.com/developers.md): API keys and scopes, MCP setup for Claude, Cursor, VS Code, Codex and Gemini, endpoints, errors. Section index: [/developers/llms.txt](https://useguidon.com/developers/llms.txt).
- [JavaScript/TypeScript SDK source](https://github.com/two-steps-studio/guidon/tree/main/packages/sdk-js): typed REST API client; npm release pending.
- [Python SDK source](https://github.com/two-steps-studio/guidon/tree/main/sdk/python): typed Python REST API client; PyPI release pending.
- [CLI source](https://github.com/two-steps-studio/guidon/tree/main/packages/cli): terminal and CI client; npm release pending.
- [Agent Plugin](https://github.com/two-steps-studio/guidon/blob/main/plugin.json): portable product/docs MCP connections and agent skills.
- Authentication section index: [/auth/llms.txt](https://useguidon.com/auth/llms.txt).
- [Docs MCP server](https://useguidon.com/api/mcp/docs): search and read these docs over MCP, no sign-in (tools `search_docs`, `read_doc`).
- [Ask](https://useguidon.com/ask): NLWeb endpoint - `POST {"query":{"text":"..."}}` answers from the public docs.
- [Authentication](https://useguidon.com/auth.md): OAuth 2.1 for MCP clients and apps, API keys for scripts - discovery, registration, tokens, scopes, errors, revocation.
- [Pricing](https://useguidon.com/pricing.md): Guidon Cloud plans, limits and features as Markdown.

## Pages

- [Homepage](https://useguidon.com/): what Guidon is and its features. Also served as Markdown to `Accept: text/markdown` and `?mode=agent`, or at [/index.md](https://useguidon.com/index.md).
- [Developers](https://useguidon.com/developers)
- [About](https://useguidon.com/about): who makes Guidon ([Markdown](https://useguidon.com/about.md))
- [Contact](https://useguidon.com/contact): support email, privacy requests, bug reports ([Markdown](https://useguidon.com/contact.md))
- [Sign up](https://useguidon.com/auth/signup)
- [Terms of Service](https://useguidon.com/legal/terms)
- [Privacy Policy](https://useguidon.com/legal/privacy)
- [Sitemap](https://useguidon.com/sitemap.xml)

## Discovery

- [Agentic Resource Discovery catalog](https://useguidon.com/.well-known/ard.json) (also `/.well-known/ai-catalog.json`)
- [MCP server card](https://useguidon.com/api/mcp/server-card) and the [docs server's card](https://useguidon.com/api/mcp/docs/server-card)
- [Agent skills index](https://useguidon.com/.well-known/agent-skills/index.json): `guidon-tasks` - how to work through Guidon tasks
- [Agent skill source files](https://github.com/two-steps-studio/guidon/tree/main/skills): `guidon-tasks`, `guidon-api` and `guidon-cli`; install an individual skill with `npx skills add two-steps-studio/guidon --skill <name>`
- [API catalog](https://useguidon.com/.well-known/api-catalog) (RFC 9727), [OpenAPI](https://useguidon.com/openapi.json)
- [Structured data feed](https://useguidon.com/feeds/site.jsonl) (schema.org JSONL, listed in [schemamap.xml](https://useguidon.com/schemamap.xml))