Coding Agents

The ws CLI integrates with coding agents such as Claude Code, Cursor, Codex, and Copilot. After configuration, agents can manage tasks, move work items through workflows, and run tests from your editor.

Note: This page explains how to connect an editor agent to the ws CLI. For server-side coding agents, see Coding Agent Runner. Windshift runs one container per job and opens draft pull requests.

Quick Start

Run ws init in your project root:

ws init

On a new machine, ws init opens an OAuth-style browser flow and writes the global configuration (~/.config/ws/config.toml). It then runs the project tier:

1. Queries the workspace for item types, statuses, and workflow configuration.
2. Generates WINDSHIFT.md with command reference and workspace-specific configuration.
3. Updates CLAUDE.md or AGENTS.md, if present, with a reference to WINDSHIFT.md.
4. Creates or updates ws.toml with workspace settings and generated status aliases.

Flags

To refresh only WINDSHIFT.md, run ws config docs. This command does not change ws.toml, CLAUDE.md, or AGENTS.md.

What Gets Generated

ws init creates WINDSHIFT.md in your project root. Agents read this file to learn about your workspace and available commands.

The generated file includes:

Run ws init again after you change workspace configuration, such as statuses, item types, or workflow transitions. This keeps the file in sync.

Claude Code

If CLAUDE.md exists in your project root, ws init adds a reference to WINDSHIFT.md. Claude Code then reads it.

Allow the ws Tool

Add ws to your allowed tools in .claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "Bash(ws *)"
    ]
  }
}

This lets Claude Code run ws commands without asking for approval each time.

What Agents Can Do

After you configure the integration, you can ask your agent to:

"Check what tasks are assigned to me"
→ ws task mine

"Move ENG-142 to in progress"
→ ws task move ENG-142 progress

"Create a bug for the auth redirect issue"
→ ws task create -t "Auth redirect fails on logout" --type 2   # type ID for Bug

"What's the status of ENG-138?"
→ ws task get ENG-138
# Or filter your task list:
→ ws task mine | jq '.[] | select(.key == "ENG-138")'

The agent reads WINDSHIFT.md to find the statuses, item types, and transitions available in your workspace.

Custom Slash Commands

Claude Code supports custom slash commands in .claude/commands/. Create shortcuts for common ws operations that the whole team can use.

Create a file at .claude/commands/add-task.md:

Create a new task in the current Windshift workspace.

Use the ws CLI to create a task with the provided arguments:
- Title: $ARGUMENTS

Steps:
1. Run `ws task create --title "$ARGUMENTS"`
2. Show the created task key and status

Team members can now type /add-task Fix the login redirect bug in Claude Code. They do not need to remember the CLI syntax.

More examples:

.claude/commands/my-tasks.md - list assigned tasks:

List my current tasks from Windshift.

Run `ws task mine` and summarize the results. Group by status.

.claude/commands/start-task.md - pick up a task:

Start working on a Windshift task.

1. Run `ws task move $ARGUMENTS progress` to move the task to in progress
2. Read the task details and summarize what needs to be done

Commit .claude/commands/ to the repository so the whole team can use the same commands.

Other Agents

For agents that use AGENTS.md, such as Cursor or Codex, ws init updates that file automatically. It works the same way as CLAUDE.md.

For an agent that uses another configuration file, add a reference to WINDSHIFT.md manually. Point the agent configuration to WINDSHIFT.md so it can read workspace commands and configuration.

Example for a generic agent config:

See WINDSHIFT.md for Windshift CLI commands and workspace configuration.

Status Aliases

ws init generates aliases so agents can use consistent commands regardless of the workspace status names. The default aliases are:

ws init saves these aliases in ws.toml. You can customize them:

[status_aliases]
done = "Ready for QA"
progress = "Working"
review = "Peer Review"
todo = "Backlog"
blocked = "On Hold"

Agents use aliases in commands such as ws task move ENG-142 done. The CLI resolves the alias to the actual status name. See CLI Configuration for details.

Example Workflow

A typical session with a coding agent:

# Developer asks the agent to check their tasks
ws task mine -o table
# KEY        TITLE                    STATUS        ASSIGNEE
# ENG-142    Fix auth redirect        Open          alice
# ENG-155    Add rate limiting        Open          alice

# Agent picks up a task and moves it to in progress
ws task move ENG-142 progress

# Developer works on the fix with the agent's help...

# Agent moves the task to review when done
ws task move ENG-142 review

# Agent creates a follow-up task if needed
# (--type and --status take numeric IDs from `ws item-type ls` / `ws status ls`)
ws task create -t "Add auth redirect tests" --type 1

The agent handles workflow transitions while the developer focuses on the code.