Agentic coding with Project Feed
Give a coding agent access to project tasks through the API, CLI, or MCP. Choose its permissions and set up hooks to keep progress reports current.
Keep agent work in project tasks
An agent can read task requirements, update the checklist as it works, and leave a comment with its changes and test results. The setup below connects the agent to Project Feed. Optional hooks check for task updates after code edits and commits.
Choose how the agent connects
Use MCP when
- The agent talks to Project Feed through tools in a client such as Claude Code or Codex.
- You want the agent to call tasks, posts, docs, and search without shell access.
Quick start
- Create an API key. For an agent that works across your workspaces, create a personal token under Account > Tools & tokens with the workspaces and scopes it needs. For a single workspace, a workspace key from the workspace's Developers settings also works. See Authentication and Scopes and token types.
- Install the CLI and sign in. The prompt keeps the key out of your shell history. To skip the prompt, set the key in
PROJECT_FEED_API_KEYinstead of passing it as a flag.
npm install -g pfeed-cli
pf auth login
pf quickstartpf quickstart asks for a key when none is set, then sets a default project and creates one if the workspace has none. It needs an interactive terminal. With a personal token, choose a workspace first (step 3).
- Choose a workspace. A workspace key is already tied to one workspace. A personal token works across workspaces, so commands need a target: pass
--workspace <slug>, setPROJECT_FEED_WORKSPACE, runpf --workspace <slug> link <project>in the repository to store it for that directory, or runpf config set defaultWorkspace <slug>. - Check the result.
pf auth checkshows which credential is active, where it came from (flag, environment, .env, or profile), and its effective scopes. When an agent misbehaves, trust that output over your assumptions. A .env file in the working directory can replace the stored credential.
export PROJECT_FEED_WORKSPACE=<workspace-slug>
pf auth checkTell the agent the rules
Put the task workflow in the instruction file your agent reads at the start of a session, such as AGENTS.md or CLAUDE.md. The agent then knows the workflow without being told each session. Keep the Project Feed section short.
# AGENTS.md
## Project Feed task workflow
- Track every non-trivial change as a Project Feed task with the `pf` CLI.
- Before editing code, find the matching open task or create one, then move it
to in_progress:
- `pf tasks list --project <project-id> --status todo`
- `pf tasks create --project <project-id> --title "..." --description "..."`
- `pf tasks edit <task-id> --status in_progress`
- While working, keep the task current, not just at the end.
- Checklist: `pf checklist add <task-id> --text "..."`, then
`pf checklist check <task-id> <item-id>` as each item lands.
- Comments at checkpoints: `pf tasks comment add <task-id> --content "what changed, what was validated, what is next"`
- When the planned work is complete: `pf tasks edit <task-id> --status in_review`.
Never mark a task done unless a human explicitly asks.
## Commands
- `pf tasks list --project <project-id> --status in_progress --json` lists open work
- `pf tasks view <task-id>` shows full task detail
- `pf checklist list <task-id>` shows checklist state
- `pf auth check` confirms which credential and scopes are active
## Project Feed limits
- Use pf handoffs wait --json as a local background command to wait for work.
If only MCP is available, poll 30 seconds apart, or 60 seconds when empty.
- If the MCP client uses a 2025 protocol version, keep one session for the
whole run. Do not call initialize per tool call, and end the session with
DELETE /api/mcp when you finish. The 2026 transport has no session.
- After a rate-limit error, wait the seconds it reports before trying again.
- When you retry a write that accepts requestKey or idempotencyKey, send the
same value. For other writes, check whether the first attempt went through
before retrying.
- Use one background wait per receiving credential. Do not wrap pf handoffs list in a tight loop.
- Change up to 50 tasks with one bulk call instead of one call per task.Instructions alone drift: agents forget standing rules mid-session. The task-sync hooks page shows how to check for task updates after code edits and commits. The limits section comes from the integration guidelines, which explain each rule.
Ways to connect an agent
Read and update workspace content with scoped API credentials. Personal tokens can access multiple workspaces. Workspace keys apply to one workspace.
Use pf from the terminal with --json for structured output. Use pf api to call endpoints without a dedicated CLI command.
Connect Claude Code, Codex, or another compatible MCP client to the hosted server. Its tools use your credentials to access workspace content.
Read the documentation index at /llms.txt and every docs page as one Markdown file at /llms-full.txt. Add .md to a docs page URL to read just that page. The REST API is described at /openapi.json, with an OpenAPI 3.1 version at /openapi-3.1.json.
Next: keep tasks in sync automatically
Three Claude Code hooks inject open tasks into every prompt, block the end of a turn when code changed but no task was touched, and nudge after every commit. Set up task-sync hooks