Coding Agents

The ws CLI integrates with coding agents like Claude Code, Cursor, Windsurf, and Copilot. Once configured, agents can manage tasks, move work items through workflows, and run tests without leaving your editor.

Note: This page covers wiring an editor agent to the ws CLI. To run coding agents server-side inside Windshift (one container per run, with automatic draft pull requests), see Coding Agent Runner.

Quick Start

Run ws init in your project root:

ws init

On a brand-new machine, ws init first runs an OAuth-style browser flow to mint a token and writes the global config (~/.config/ws/config.toml). Once that's in place, it runs the project tier and:

1. Queries your workspace for item types, statuses, and workflow configuration
2. Generates a WINDSHIFT.md file with commands reference and workspace-specific config
3. Updates CLAUDE.md or AGENTS.md (if they exist) to include a reference to WINDSHIFT.md
4. Creates or updates ws.toml with workspace settings and auto-generated status aliases

Flags

If you only want to refresh WINDSHIFT.md (without touching ws.toml, CLAUDE.md, or AGENTS.md), run ws config docs.

What Gets Generated

ws init creates a WINDSHIFT.md file in your project root. This file is what agents read to understand your workspace and available commands.

The generated file includes:

Re-run ws init after changing workspace configuration (adding statuses, item types, or workflow transitions) to keep the file in sync.

Claude Code

If a CLAUDE.md file exists in your project root, ws init automatically adds a reference to WINDSHIFT.md so Claude Code picks it up.

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 prompting for approval each time.

What Agents Can Do

With the integration configured, 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 know which statuses, item types, and transitions are available in your workspace.

Custom Slash Commands

Claude Code supports custom slash commands via .claude/commands/. You can create shortcuts for common ws operations that your 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

Now anyone on the team can type /add-task Fix the login redirect bug in Claude Code to create a task without remembering the exact 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 the .claude/commands/ directory to your repo so the whole team has access to the same commands.

Other Agents

For agents that use AGENTS.md (like Cursor or Windsurf), ws init updates that file automatically - same as with CLAUDE.md.

For agents that use a different config file, add a reference to WINDSHIFT.md manually. The pattern is the same regardless of agent: point the agent's config to WINDSHIFT.md so it can read your workspace commands and configuration.

Example for a generic agent config:

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

Status Aliases

ws init auto-generates aliases so agents can use consistent commands regardless of your actual workspace status names. The default aliases:

These are saved in ws.toml and can be customized:

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

Agents use aliases in commands like ws task move ENG-142 done - the CLI resolves the alias to the actual status name. See CLI Configuration for more on status aliases.

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 the workflow transitions while the developer stays focused on the code.