Skip to main content

Windsurf (Codeium)

Windsurf is Codeium's AI-native IDE built on a VS Code fork, with agentic coding capabilities in its GUI (Cascade).

AgentXchain does not currently ship a native Windsurf connector. Windsurf is a GUI-first IDE — it does not expose a documented headless CLI mode for programmatic agent interaction. The local_cli adapter cannot spawn Windsurf as a subprocess today.

The closest supported path is to use Windsurf as your editing environment while connecting a separate CLI agent as the governed runtime.

Read the Authority Model before you configure the terminal-side runtime. Windsurf is the editor, not the governed runtime.

Recommended setup: Windsurf as editor + CLI agent runtime​

Edit your code in Windsurf. Run AgentXchain in Windsurf's integrated terminal with a proven CLI agent handling the governed turns.

Configuration (Claude Code as runtime)​

{
  "runtimes": {
    "claude-dev": {
      "type": "local_cli",
      "command": ["claude", "--print", "--dangerously-skip-permissions", "--bare"],
      "cwd": ".",
      "prompt_transport": "stdin"
    }
  },
  "roles": {
    "dev": {
      "runtime": "claude-dev",
      "mandate": "Implement features and fix bugs",
      "write_authority": "authoritative"
    }
  }
}

Configuration (OpenAI Codex CLI as runtime)​

{
  "runtimes": {
    "codex-dev": {
      "type": "local_cli",
      "command": ["codex", "exec", "--dangerously-bypass-approvals-and-sandbox", "{prompt}"],
      "cwd": ".",
      "prompt_transport": "argv"
    }
  },
  "roles": {
    "dev": {
      "runtime": "codex-dev",
      "mandate": "Implement features and fix bugs",
      "write_authority": "authoritative"
    }
  }
}

Minimal working example​

agentxchain init --governed --template api-service --goal "Build a REST API" --dir my-project -y
cd my-project
# Edit agentxchain.json to use one of the CLI runtime configs above.
agentxchain doctor
agentxchain connector check
agentxchain connector validate <runtime_id>   # use claude-dev or codex-dev from your config
agentxchain run

If you prefer the guided interactive scaffold, run agentxchain init --governed without -y, then update agentxchain.json with your chosen CLI runtime config before running agentxchain connector check and agentxchain connector validate <runtime_id>.

Using Windsurf's built-in AI alongside AgentXchain​

Windsurf's Cascade (agentic mode) and autocomplete work inside the editor while AgentXchain governs the structured delivery process in the terminal. They are complementary:

  • Windsurf Cascade — ad-hoc coding assistance within the editor
  • AgentXchain — governed multi-agent turns, role enforcement, artifact tracking, phase gates
  • Authority model — still defined by the separate governed runtime in the terminal, not by Windsurf itself

Future: if Windsurf adds a headless CLI​

If Windsurf ships a documented headless CLI mode in the future, the generic local_cli adapter would support it with a config like:

{
  "runtimes": {
    "windsurf-dev": {
      "type": "local_cli",
      "command": ["windsurf", "<future-cli-flag>"],
      "cwd": ".",
      "prompt_transport": "stdin"
    }
  }
}

This is speculative and not a working config today. Check Windsurf's documentation for the latest CLI capabilities.

Gotchas​

  • No headless CLI mode: Windsurf's AI capabilities (Cascade, Tab, Chat) are GUI-only. You cannot spawn Windsurf as a subprocess for governed turns.
  • Terminal works fine: Windsurf's integrated terminal runs agentxchain commands normally — the limitation is only about using Windsurf as the agent runtime.
  • Model routing: Windsurf uses its own model routing layer (Codeium infrastructure). The models available in Windsurf are separate from the models you configure in your AgentXchain runtime.