Skip to content

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.

Use something else when

  • Your scripts or the agent's terminal run commands: use the pf CLI.
  • Your own service calls Project Feed over HTTP: use the REST API.

Quick start

  1. 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.
  2. 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_KEY instead of passing it as a flag.
Shell
npm install -g pfeed-cli
pf auth login
pf quickstart

pf 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).

  1. 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>, set PROJECT_FEED_WORKSPACE, run pf --workspace <slug> link <project> in the repository to store it for that directory, or run pf config set defaultWorkspace <slug>.
  2. Check the result. pf auth check shows 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.
Shell
export PROJECT_FEED_WORKSPACE=<workspace-slug>
pf auth check

Tell 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.

Markdown
# 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.

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

Image preview
100%