Basic Usage

Auto-Coder.Chat offers three usage modes for different development scenarios.

cd your-project
auto-coder.chat

Traditional Mode (/auto)

The most straightforward approach — use the /auto command to have AI analyze and execute coding tasks:

/auto Add a user login feature

Simply follow /auto with your request. The AI executes the task synchronously in the current session, and you can watch progress in real time.

File References

Use @ to reference file paths, and press Tab for auto-completion:

/auto Refactor the auth logic in @src/utils/auth.ts

Session Management

# Start a brand new session
/auto /new

# List all previous sessions
/auto /list

Async Mode (/async)

Async mode is Auto-Coder.Chat's killer feature — submit tasks to run in the background. You can submit multiple tasks simultaneously, and they'll execute in parallel with results automatically merged.

Submit an Async Task

/async /name my-job /time 40m Refactor the error handling logic across the project

• /name my-job — Name the task (required)
• /time 40m — Set maximum runtime (e.g., 40m for 40 minutes)
• Followed by your request

For longer requests, wrap them in double quotes or triple quotes:

/async /name my-job /time 40m "Write a new markdown file introducing what this project does"

/async /name my-job /time 40m '''
1. Refactor the auth module
2. Add unit tests
3. Update related docs
'''

Tasks run in an isolated git worktree in the background, without affecting your current work:

Monitor Async Tasks

# List all async tasks
/async /list

# View details of a specific task
/async /task my-job

Inspect with External Tools

Async tasks run in isolated working directories. You can open them with any external tool (e.g., Cursor, VS Code):

!cursor ~/.auto-coder/async_agent/tasks/my-job

The ! prefix executes an external shell command.

Merge Async Tasks

When you're happy with the results, merge the task back into the main branch:

/auto /merge my-job

SubAgents Cowork Mode

Workflow mode lets you define SubAgent workflows, breaking complex tasks into multiple Agents executed in stages (DAG orchestration). Ideal for large-scale refactoring, design reviews, and multi-step collaboration.

Invoking a Workflow

There are two ways:

Shortcut (recommended for daily use):

$plan Refactor the user authentication module

$ followed by the workflow name, then a space and your request. This is equivalent to:

/workflow plan query="Refactor the user authentication module"

Standard command (supports additional parameters):

/workflow plan query="Refactor the auth module" env=prod

Type $ and press Tab to auto-complete available workflow names.

Get Workflows

Visit the SubAgents Cowork Market to find community-contributed workflows. Download and place them in ~/.auto-coder/.autocoderworkflow/ to use.

Some common workflows available on the market:

For example, after downloading the plan workflow, run a full plan-to-implementation flow:

$plan '''
1. Refactor the auth module to support OAuth2
2. Add unit test coverage
3. Update API documentation
'''

The plan workflow executes sequentially: Context Gathering → Design Solution (output to docs/) → Code Implementation → Verification & Testing → Code Review, with each stage potentially using a different model.

Configure Workflow Models

Before using a workflow, make sure the models it references are properly configured.

1. Check the workflow YAML files in ~/.auto-coder/.autocoderworkflow/ to find the models they define (e.g., model: "volcengine/deepseek-v3-2")
2. Run /models /list to see your currently configured models
3. If a workflow references a model you haven't configured, you can either:
   • Add the required model following the Model Configuration guide
   • Or edit the model field in the workflow file to use a model you already have

Tip: Workflow files may reference different models in globals.model and individual agents[].model entries — make sure all referenced models are configured.

Workflow YAML Structure

Workflows are defined as YAML files with the following core structure:

apiVersion: autocoder/v1
kind: SubagentWorkflow
metadata:
  name: my-workflow
  description: "My custom workflow"
spec:
  globals:
    model: "volcengine/deepseek-v3-2"

  vars:
    project_type: "*"

  agents:
    - id: context
      model: "volcengine/deepseek-v3-2"
      runner: terminal
    - id: coder
      model: "volcengine/deepseek-v3-2"
      runner: terminal

  steps:
    - id: gather_context
      agent: context
      with:
        user_input: |
          ${vars.query}
          Analyze project context and find relevant files.
      outputs:
        attempt_raw: "${attempt_result}"

    - id: write_code
      needs: [gather_context]
      agent: coder
      with:
        user_input: |
          Implement the code based on context.
      outputs:
        attempt_raw: "${attempt_result}"

Key concepts:

• agents — Define participating Agents, each with its own model and runner
• steps — Orchestrated as a DAG (directed acyclic graph), needs declares dependencies
• vars — Global variables; ${vars.query} references the user's input
• outputs — Each step's output can be referenced by subsequent steps

Workflow Search Paths

The system searches for workflow files in this priority order:

1. ./.autocoderworkflow/ — Project-level (highest priority)
2. ./.auto-coder/.autocoderworkflow/ — Project-level
3. ~/.auto-coder/.autocoderworkflow/ — Global

You can create .autocoderworkflow/ in your project directory for project-specific workflows, or place shared workflows in the global directory.

Command Quick Reference

Next Steps

• See Project Structure to understand project organization
• See Best Practices for tips on efficient usage