Agentic Usage

AI agents that can run shell commands can use the Plot CLI to read and update real workspace data. This lets the agent work from tasks, projects, docs, comments, and team context instead of relying only on a prompt or local files.

Automatic Setup

Run:

plot setup

The setup command installs or refreshes the bundled plot-cli skill for supported local agent tools. It can install skill files in detected global and project-level agent roots, such as Claude, Cursor, and agents that read from ~/.agents.

For a non-interactive setup with defaults:

plot setup --yes

To choose specific agents or install scope:

plot setup --agent claude --global
plot setup --agent cursor --project

Requirements

• The plot binary is installed and available on PATH.
• You have authenticated with plot login or plot login --token.
• The active workspace is set correctly with plot workspace use <slug>.
• Your agent can run shell commands.

What Agents Can Do

With the CLI, agents can:

• Read full task details before starting work.
• Pull project, collection, team, status, label, and user context.
• Search for related tasks, docs, comments, decisions, and prior work.
• Update task status, assignee, labels, dates, parent tasks, and dependencies.
• Add comments with progress, blockers, verification notes, and handoff context.
• Create shared documents for PRDs, plans, briefs, and learnings.
• Check inbox notifications and recent activity.

How Agents Should Use It

When an agent starts from a task ID, it should read the task first:

plot task get ENG-042 --format json
plot comment list --entity task --id ENG-042 --format json

If the task belongs to a project, it should read the project too:

plot project get checkout-redesign-a1b2c3d4e5f6 --format json
plot project summary checkout-redesign-a1b2c3d4e5f6 --format json

If more context is needed, it should search:

plot search "checkout launch decisions" --format json

When work starts, the agent can move the task forward:

plot task-status list --team ENG --format json
plot task update ENG-042 --status "In Progress"

When work reaches a useful checkpoint, the agent should leave a comment:

plot comment add --entity task --id ENG-042 --body "Implemented the checkout empty state and verified it with the dashboard test suite."

This keeps progress attached to the task so another person or agent can pick up the thread later.

Shared Context

Plot is useful for agents because the workspace is shared. A note written in a private chat disappears from the team's normal view of work. A Plot comment, task update, or document stays attached to the project history.

Use Plot documents for shared artifacts:

plot doc create --team ENG --name "Checkout QA plan" --description "Regression checklist for the checkout launch."

Use comments for task-specific updates:

plot comment add --entity task --id ENG-042 --body "Blocked by ENG-041. Waiting on final API shape."

Use dependencies when one task must wait for another:

plot task add-dependency --task ENG-042 --blocked-by ENG-041

Creating Task Trees

Agents can create a parent task with subtasks and dependencies from JSON:

cat <<'JSON' | plot task create-tree --format json
{
  "name": "Ship checkout polish",
  "team": "ENG",
  "project": "checkout-redesign-a1b2c3d4e5f6",
  "subtasks": [
    { "name": "Fix empty state", "ref": "empty-state" },
    { "name": "Add regression coverage", "blockedBy": ["@empty-state"] }
  ]
}
JSON

task create-tree supports one level of subtasks. Subtasks inherit the parent team, project, assignee, and visibility unless the JSON overrides them.

Good Agent Prompts

You can give an agent a short prompt if the relevant work already exists in Plot:

Work on ENG-042. Read the task, project, comments, and related docs before changing code. Leave a comment with what you changed and how you verified it.

For planning:

Create a launch plan for the Acme campaign in Plot. Search prior Acme work first, write the plan as a Plot doc, then create implementation tasks if the plan is ready.

Security

Agents use your existing CLI authentication. Treat workspace data and access tokens with the same care as your private repositories.

Do not paste personal access tokens, OAuth credentials, or private customer data into prompts, comments, public issues, or logs.