tooling.json

tooling.json is the trust boundary for your Swytchcode project.

It defines what your project is allowed to execute. Every method and workflow that Swytchcode can run must be explicitly listed in this file. If a tool is not present here, execution is blocked.

This file also marks the root of a Swytchcode project. Whenever a command is executed, the CLI searches upward from the current directory until it finds a .swytchcode/tooling.json file.

project/
├── .swytchcode/
│   ├── tooling.json
│   ├── integrations/
│   └── ...
└── ...

Important

Swytchcode follows a fail-closed model. Nothing can execute unless it has been explicitly added to tooling.json.

File Structure

A minimal tooling.json looks like this:

{
  "version": "1.0",
  "mode": "production",
  "editor": "cursor",
  "integrations": {},
  "tools": {}
}

As your project grows, Swytchcode automatically updates this file whenever you add integrations, methods, or workflows.

Top-level Fields

version

Defines the schema version of the configuration file.

{
  "version": "1.0"
}

This value is created automatically during project initialization.

mode

Controls which environment Swytchcode executes against.

{
  "mode": "production"
}

Supported values:

Value	Description
`production`	Uses the production endpoint defined in `manifest.json`.
`sandbox`	Uses the sandbox endpoint defined in `manifest.json`.

The execution mode determines which base URL Swytchcode resolves before sending an API request.

editor

Specifies the coding agent or editor configured for the project.

{
  "editor": "cursor"
}

Supported editors:

cursor
claude
codex
copilot
gemini
hermes
openclaw
windsurf
none

Swytchcode uses this value during project initialization to generate editor-specific rules and MCP configuration.

integrations

Tracks every integration installed in your project.

{
  "integrations": {
    "stripe.stripe": {
      "version": "v2"
    },
    "github.github": {
      "version": "v1"
    }
  }
}

Each entry pins a specific version so every developer and AI agent uses the same integration contract.

tools

The tools object contains every trusted method and workflow available for execution.

{
  "tools": {
    "stripe.create_payment": {},
    "github.repo.star": {}
  }
}

Nothing outside this list can be executed.

The following sections explain how methods and workflows are represented.

permissions

Optionally restricts network and filesystem access.

{
  "permissions": {
    "network": [
      "api.stripe.com"
    ]
  }
}

If omitted, Swytchcode applies no additional restrictions.

Method Entries

A method represents a single executable API operation.

Each method contains:

type
summary
description
integration
inputs

Example:

{
  "api.cluster.create": {
    "type": "method",
    "summary": "Create a new cluster instance",
    "desc": "Create a new cluster instance",
    "integration": "weaviate.lyrid@v1",
    "inputs": [
      {
        "Authorization": {
          "LOCATION": "header",
          "TYPE": "STRING"
        }
      }
    ]
  }
}

Fields

Field	Description
`type`	Always `"method"`
`summary`	Short description of the method
`desc`	Detailed description
`integration`	Integration providing the method
`inputs`	Required request inputs

Methods are added automatically when you run:

swy add method <canonical_id>

Workflow Entries

A workflow represents multiple methods executed in sequence.

Unlike methods, workflows do not duplicate their internal steps as top-level tools.

Example:

{
  "workflow.example": {
    "type": "workflow",
    "name": "Example Workflow",
    "integration": "weaviate.lyrid@v1",
    "steps": [
      {
        "canonical_id": "api.cluster.create",
        "index": 0,
        "integration": "weaviate.lyrid@v1",
        "inputs": []
      },
      {
        "canonical_id": "api.cluster.update",
        "index": 1,
        "integration": "weaviate.lyrid@v1",
        "inputs": []
      }
    ]
  }
}

Workflow Fields

Field	Description
`type`	Always `"workflow"`
`name`	Workflow name
`integration`	Integration containing the workflow
`steps`	Ordered execution steps

Each step contains:

canonical_id
integration
inputs
index

The index determines execution order.

Step 0
   ↓
Step 1
   ↓
Step 2

When a workflow executes, Swytchcode runs each step sequentially.

Permissions

The optional permissions block limits where tools are allowed to interact.

Example:

{
  "permissions": {
    "network": [
      "api.stripe.com",
      "api.sendgrid.com"
    ],
    "filesystem": [
      "/var/app/uploads"
    ]
  }
}

Network

Defines an allowlist of hosts.

If a request targets any other hostname, execution fails.

{
  "network": [
    "api.stripe.com"
  ]
}

Filesystem

Defines directories Swytchcode may access.

{
  "filesystem": [
    "/var/app/uploads"
  ]
}

Filesystem permissions are reserved for future enforcement.

Managing Tools

Most developers should never edit tooling.json manually.

The CLI keeps this file synchronized.

Add a method

swy add method stripe.create_payment

# shorthand - identical to the above
swy add stripe.create_payment

add method reads the Wrekenfiles and bundles already fetched under .swytchcode/integrations/, resolves the method’s input/output STRUCTs into a concrete schema, and writes the result into tooling.json.tools. It also stores a method_hash (a SHA-256 of the Wrekenfile entry) alongside the tool - swy sync uses this hash later to warn you if the upstream definition has changed since you added it.

If multiple integrations expose the same canonical ID, Swytchcode asks you to select the correct one interactively. In non-interactive contexts (CI, scripts), pass an explicit [email protected] spec ahead of the canonical ID to disambiguate instead of relying on the picker - see swy add method [spec] <canonical_id> in the Command Reference.

Two flags matter here:

--all <project> adds every method for a project at once, skipping any canonical ID that’s already present - useful right after swy get when you want the whole integration enabled rather than cherry-picking methods one at a time.
--no-auto-install skips auto-downloading missing library dependencies for multi-library workflows. Use it if you want to add a workflow’s entry without silently pulling in every dependency it touches.

Add a workflow

swy add workflow workflow.payment.checkout

Unlike methods, a workflow entry does not duplicate its steps as separate top-level tools in tooling.json.tools - see Workflow Entries below. Missing integrations referenced by the workflow’s steps are downloaded automatically before the entry is written.

Register an integration

swy add integration stripe.stripe@v2

Registers an integration without downloading its bundle.

List enabled tools

swy list tooling
swy list tooling stripe        # filter by a pattern
swy list tooling --json

swy list reads only local state (.swytchcode/integrations and tooling.json) - it never calls the registry, so it works offline. The tooling filter specifically reads tooling.json.tools and shows only what’s been explicitly enabled via swy add, as opposed to swy list methods / swy list workflows, which show everything available in the fetched bundles whether or not it’s enabled.

--json returns a machine-readable array: [{ "canonical_id": "stripe.create_payment", "integration": "stripe.stripe@v2" }, ...]. Always verify a tool appears in this output - not just in swy list methods - before generating execution code or wiring it into an AI agent’s tool list; a method existing in the bundle doesn’t mean it’s trusted for execution.

Best Practices

Do not edit generated entries unless necessary.
Commit tooling.json to version control.
Use swy add instead of manually creating tools.
Keep integration versions pinned for reproducible execution.
Review enabled tools periodically to remove unused capabilities.

Now that you understand how Swytchcode defines trusted tools, continue with:

Next Steps

manifest.json

Learn how integrations define endpoints, authentication, retries, and execution policies.

policies.json

Learn how to apply runtime guardrails and validation rules before execution.