Using Swiftide with coding agents

Your coding agent, such as Claude Code, Cursor or Codex, can write Swiftide code that compiles against 0.34.

Swiftide is pre-1.0, and minor releases break APIs. Release 0.33 changed system prompts, hook signatures, command output and the AWS Bedrock module. A model that learned an older release writes code that no longer compiles. Each source below gives the agent the current API, and the AGENTS.md block at the end pins the rules in your project.

Source	What the agent gets
Skill	Rules, gotchas and compiled snippets for the current API
Context7	Search over the examples, the skill and the crate sources
llms.txt files	This site as plain text
Page Markdown	One page as Markdown
API docs	Exact signatures, as HTML or rustdoc JSON
Examples	Programs that compile

Release status

The skill, context7.json and the four showcase crates ship with the 0.34 release. These docs pin the release commit, and the skill describes the APIs at that commit.

Skill

The Swiftide skill is a set of instructions that the agent loads when the task needs it. Install it with the skills CLI from npm (needs Node.js):

npx skills add bosun-ai/swiftide

Without Node.js, copy the skills/swiftide folder from the pinned commit into the skills directory of your agent.

SKILL.md covers feature flags, OpenAI-compatible endpoints, tools, hooks, structured stops, human approval, MCP (Model Context Protocol) toolboxes, tasks and pipelines, and ends with a checklist. Four reference files go deeper: agents.md, tasks.md, pipelines.md and integrations.md. Every snippet in them is copied from compiled code in the swiftide repository, and names its source file.

The agent picks the skill up when a Rust project depends on swiftide or one of its crates, when you ask for an agent, task graph or RAG (retrieval-augmented generation) pipeline in Rust, or when it fixes a missing feature flag.

Context7

Context7 indexes the swiftide repository under the library ID /bosun-ai/swiftide. With the Context7 MCP server installed, ask the agent to look up Swiftide in Context7, or give it the ID.

Context7 indexes the default branch, which can hold APIs that are not released yet. Check what it returns against the version in your Cargo.lock.

The repository’s context7.json limits the index to examples, skills and the source folders of the crates, and adds nine rules that the AGENTS.md block below also covers.

llms.txt files

The site publishes plain-text versions of itself for language models. /llms.txt states the version these docs describe, 0.34, and links the others.

File	Contents
/llms.txt	An index with the pinned version and links to the files below
/llms-full.txt	Every page in one file
/llms-small.txt	The start pages and core guides, without recipes, showcases, integrations or reference
/_llms-txt/agents.txt	Agents: tools, hooks and executors
/_llms-txt/tasks.txt	Typed task graphs
/_llms-txt/indexing-and-querying.txt	Indexing and query pipelines
/_llms-txt/integrations.txt	Model providers, vector stores and other integrations
/_llms-txt/showcases.txt	The four showcase programs and their output

The full and small files start with the home page, followed by the Start pages. None of the files include the changelog. A section file is the smallest useful input when the agent works on one part, such as a task graph.

Page Markdown

Every page is also served as Markdown at its URL plus .md, for example https://swiftide.rs/start/installation.md. Snippets are expanded into code, so the agent sees the same compiled Rust as you do.

The buttons next to each page title do the same by hand. Copy page copies the page as Markdown, for pasting into a chat. View as Markdown opens the .md version. Open in ChatGPT and Open in Claude start a conversation about the page.

API docs

The API docs on docs.rs are the most reliable source of exact signatures. docs.rs builds swiftide with every feature flag on and labels each item with the flag it needs.

docs.rs also serves rustdoc JSON. The swiftide crate only re-exports the other crates, so its JSON holds re-export stubs and no signatures. Fetch the JSON of the crate that defines the items, such as swiftide-agents, swiftide-tasks, swiftide-core, swiftide-indexing, swiftide-query or swiftide-integrations. docs.rs sends it zstd-compressed, so decompress it before the agent reads it:

curl -sSL https://docs.rs/crate/swiftide-agents/0.34/json | zstd -d > swiftide-agents.json

Pin the version in the URL so the agent does not read a newer release. latest in place of the version gives the newest release instead.

Examples

The examples directory holds the single-file examples and the four showcases. Each showcase has a README, an OUTPUT.md with output from a real run, and source that this site excerpts.

From the root of a checkout of the pinned commit, an agent can run them. hello-agents uses Gemini and needs GEMINI_API_KEY. ask-your-codebase needs OPENAI_API_KEY, and its first run downloads an embedding model of about 600 MB.

cargo run -p swiftide-examples --example hello-agents
cargo run -p ask-your-codebase -- index swiftide-agents

AGENTS.md block

Paste this block into the AGENTS.md or CLAUDE.md at the root of your project. It comes from the skill’s gotchas and the rules in context7.json. Change the version line when you upgrade.

## Swiftide

This project uses swiftide 0.34 (Rust 1.97 or newer, edition 2024). Swiftide is
pre-1.0 and minor releases break APIs. Check the version in Cargo.lock, and read
https://swiftide.rs/llms.txt or https://docs.rs/swiftide/0.34/swiftide/ before
trusting examples written for older releases.

- Feature flags: default features are only `macros` (`#[swiftide::tool]`, `#[derive(Tool)]`).
  Agents need `swiftide-agents`, which also turns on `swiftide-tasks`. Each integration needs its
  own flag (`openai`, `anthropic`, `gemini`, `qdrant`, `fastembed`, `lancedb`, `duckdb`, `redb`,
  `mcp`, ...). An unresolved import under `swiftide::agents` or `swiftide::integrations` means a
  missing flag. `all` turns on only `qdrant`, `redis`, `tree-sitter`, `openai`, `fastembed`,
  `scraping`, `aws-bedrock`, `groq`, `ollama` and `pgvector`; everything else, including agents
  and tasks, needs its own flag.
- With `default-features = false`, add `macros` back. Tools and structured stops also need
  `schemars` (with `derive`) and `serde`.
- TLS needs no setup: the HTTP clients use rustls with their own crypto provider. Do not add
  `rustls` or call `install_default()` unless the app wants a specific provider.
- Tools: `#[swiftide::tool]` on an async fn that takes `&dyn AgentContext` and returns
  `Result<ToolOutput, ToolError>`. The doc comment is the tool description and a `# Arguments`
  list describes the arguments. Use `#[derive(Tool)]` for a tool with state. Return
  `ToolOutput::fail(..)` for errors the model should see and recover from.
- Run commands with `context.executor().exec_cmd(&Command::shell(..))`; `AgentContext::exec_cmd`
  is deprecated. `CommandOutput` records stdout and stderr chunks: `stdout()` and `stderr()`
  iterate over the `Bytes` chunks of one stream, and `into_string_lossy()` merges both streams
  into one `String` in the order they arrived.
- The system prompt is a `Prompt`: `.system_prompt(..)` takes anything `Into<Prompt>`, such as a
  `&str`. `SystemPrompt` no longer exists. An agent without a system prompt sends none.
- Hooks are closures that return `Box::pin(async move { Ok(()) })`; clone captured values before
  the `async move` block. Most hooks get `&mut Agent`; `on_new_message` and `on_stream` get
  `&Agent`. A hook that returns an error is logged, not propagated.
- Structured output: call `without_default_stop_tool()` before `.tools(..)`, add
  `StopWithArgs::with_parameters_schema(schema_for!(T))`, and read
  `StopReason::RequestedByTool(_, Some(payload))`. `.tools(..)` replaces any earlier list.
- `StopReason::NoNewMessages` means the model answered without a tool call or `.limit(n)` was
  reached. `limit` counts completions per `query`.
- Human approval: wrap a tool in `ApprovalRequired::new(tool)`. On
  `StopReason::FeedbackRequired`, call
  `agent.context().feedback_received(&tool_call, &ToolFeedback::approved())`, then `agent.run()`.
- Tasks: import from `swiftide::tasks`; `swiftide::agents::tasks` is deprecated. Use `Task`,
  `TaskNode` and `Transition` instead of chaining agents by hand. Give every node one transition
  and end with `task.transitions_to_finish()`. A fan-out
  (`Transition::fan_out(..).and(..).join_with(join.join())`) ends in a join node. `task.run(..)`
  returns `TaskRunOutcome::Completed(output)` or `TaskRunOutcome::Paused`; continue a paused
  task with `task.resume()`.
- OpenAI-compatible endpoints go through the `openai` flag:
  `OpenAI::builder().api_base("http://127.0.0.1:8080/v1").api_key(key)`. The URL includes the
  version prefix. `.client(..)` replaces both; whichever is called last wins.
- AWS Bedrock is `swiftide::integrations::aws_bedrock_v2` (the Converse API), behind the
  `aws-bedrock` flag.
- MCP tools are named `<server>:<tool>`. OpenAI rejects `:` in tool names, so rename them.
- Pipelines: use the same embedding model for indexing and querying, and set the vector store's
  `vector_size` to that model's dimensions. Wrap LLM clients used during indexing in
  `LanguageModelWithBackOff`.
- Before finishing: run `cargo check` with the exact features.

Verification

Ask the agent to finish with the checks from the skill. cargo check with the exact feature flags in Cargo.toml catches a missing flag as an unresolved import (error E0432).

Reference

swiftide crate root
Agent and StopReason
ToolOutput and CommandOutput
Prompt
ApprovalRequired and StopWithArgs
Task, Transition and TaskRunOutcome
OpenAI and OpenAIBuilder
aws_bedrock_v2
LanguageModelWithBackOff
skills/swiftide/SKILL.md at the pinned commit
Feature flags
Upgrading
TLS

Agents overview