How to Configure Cody Custom Commands via .vscode/cody.json to Standardize Team Prompts and Code Generation

When engineering organizations deploy AI coding assistants across their development teams, they quickly encounter an inconsistent adoption gap. While senior developers might craft comprehensive, boundary-aware prompts that yield production-grade code, other team members often rely on vague instructions like "fix this bug" or "write tests." The result is fragmented output: unit tests written in conflicting frameworks, disparate error-handling paradigms, variable naming mismatches, and missed edge cases.

Sourcegraph Cody provides a direct mechanism to resolve this disparity at the repository level: Custom Commands configured inside .vscode/cody.json. By codifying battle-tested prompts, execution modes, and precise context retrieval boundaries into a version-controlled configuration file, engineering leads can turn prompt engineering into shared, reusable team infrastructure. Every developer who clones the repository instantly inherits identical slash commands, ensuring consistent code generation, automated review standards, and reliable test synthesis across the entire codebase.

Architecture of .vscode/cody.json

Cody distinguishes between user-level custom commands (stored globally in the user profile) and workspace-level custom commands. Placing cody.json inside the repository's .vscode/ directory pins commands directly to the project's technical stack, dependencies, and architectural standards.

repository-root/
├── .vscode/
│   ├── cody.json          <-- Team custom commands definition
│   └── settings.json
├── src/
├── tests/
└── package.json

When committed to Git, Cody automatically parses .vscode/cody.json whenever a developer opens the workspace in VS Code. The configured commands appear in Cody's command palette (Option + C on macOS or Alt + C on Windows/Linux) and can be invoked directly in the Cody Chat bar as slash commands (e.g., /unit-test).

Configuration Schema Breakdown

A standard .vscode/cody.json configuration file organizes commands under a top-level commands object:

{
  "commands": {
    "command-identifier": {
      "prompt": "Detailed instruction template sent to the underlying LLM.",
      "description": "Short explanation displayed in Cody's command menu.",
      "mode": "ask",
      "context": {
        "codebase": false,
        "selection": true,
        "currentDir": false,
        "openTabs": false
      }
    }
  }
}

Every command is defined by four core attributes:

Execution Modes: Tailoring AI Output Delivery

The mode property governs the interaction model between the LLM and the developer's active editor buffer:

1. ask (Interactive Dialogue & Review):

   • Delivers the generated output into the Cody Chat panel.
   • Ideal for code reviews, architectural validations, security vulnerability scans, and complex algorithmic explanations where developers need to inspect reasoning before applying changes.

2. edit (Inline In-Place Modification):

   • Treats the prompt as an automated refactoring directive and replaces the highlighted code selection directly inside the active buffer.
   • Best suited for deterministic code transformations: type hardening, styling normalization, lint rule remediation, and converting imperative logic to declarative patterns.

3. insert (Targeted Code Scaffolding):

   • Generates code and inserts it immediately above or at the cursor/active selection.
   • Ideal for generating structured docstrings, JSDoc annotations, method boilerplate, or scaffolding new test suites into an open test file.

Context Retrieval Scoping: Balancing Quality and Latency

One of the most frequent reasons AI code assistants produce hallucinations or irrelevant boilerplate is context contamination. Providing an LLM with either too little context or an uncurated flood of repository files degrades output precision and increases token latency.

The context object in .vscode/cody.json provides granular toggles to govern Cody's context ingestion:

• selection (true / false): Passes the exact lines of code currently highlighted in the active editor buffer. For task-specific commands like /refactor-clean or /document-api, setting selection: true guarantees the model focuses squarely on the target block.
• codebase (true / false): Triggers Sourcegraph's semantic search and code intelligence across the entire repository index. Enabling this flag allows Cody to find existing helper utilities, shared domain models, assertion libraries, and mock implementations across disparate folders. However, it should only be enabled when cross-file awareness is necessary (e.g., generating unit tests that require shared test fixtures), as it adds retrieval overhead.
• currentDir (true / false): Ingests sibling files within the active file's immediate folder. This is especially useful in feature-sliced designs where a component, its styled module, and its mock data coexist in a single directory.
• openTabs (true / false): Includes content from other open editor tabs. While convenient for multi-file feature implementations, leaving this enabled globally can introduce unrelated context from background files.

Production Recipes for Engineering Teams

Below is a production-ready .vscode/cody.json demonstrating four standardized commands tailored for modern software teams.

{
  "commands": {
    "unit-test": {
      "description": "Generate standard Vitest unit tests with mocks and edge case coverage",
      "mode": "ask",
      "context": {
        "selection": true,
        "codebase": true,
        "currentDir": true,
        "openTabs": false
      },
      "prompt": "You are a senior test automation engineer. Generate a comprehensive test suite for the selected code using Vitest and @testing-library/react where applicable.\n\nStrict adherence rules:\n1. Structure all tests with the Arrange-Act-Assert (AAA) pattern.\n2. Follow existing test fixtures and mock conventions located in the codebase.\n3. Cover happy path, boundary values, null/undefined inputs, and async error rejections.\n4. Do not import external mocking libraries; use Vitest built-in vi.fn() and vi.spyOn().\n5. Provide complete, runnable test files without placeholder comments like '// implement here'."
    },
    "refactor-clean": {
      "description": "Refactor selected code to enforce strict TypeScript, immutability, and cognitive simplicity",
      "mode": "edit",
      "context": {
        "selection": true,
        "codebase": false,
        "currentDir": false,
        "openTabs": false
      },
      "prompt": "Refactor the selected code block to adhere to clean code and strict TypeScript standards:\n1. Preserve existing public API contracts, method signatures, and runtime behavior.\n2. Replace loose 'any' types with precise discriminated unions or generic constraints.\n3. Replace mutable state patterns with pure functions and immutable data updates.\n4. Extract nested ternary operators or deeply nested conditionals into clear early returns.\n5. Output ONLY the replacement code with no surrounding markdown or explanation."
    },
    "security-audit": {
      "description": "Scan selected code for security vulnerabilities, OWASP Top 10 risks, and data leakage",
      "mode": "ask",
      "context": {
        "selection": true,
        "codebase": true,
        "currentDir": false,
        "openTabs": false
      },
      "prompt": "Perform a rigorous security code review on the selected code segment.\n\nEvaluate the following vulnerability vectors:\n1. Injection flaws (SQL, NoSQL, command execution, or template injection).\n2. Broken authentication, improper authorization checks, and privilege escalation.\n3. Insecure direct object references (IDOR) and unvalidated user inputs.\n4. Secrets, API keys, or sensitive PII exposed in code or logging calls.\n5. Unhandled exception pathways that could leak stack traces.\n\nFormat your findings as: [Severity: High/Med/Low] | [Issue] | [Vulnerable Line] | [Remediation Diff]."
    },
    "doc-api": {
      "description": "Insert standard TSDoc documentation for functions, interfaces, or classes",
      "mode": "insert",
      "context": {
        "selection": true,
        "codebase": false,
        "currentDir": false,
        "openTabs": false
      },
      "prompt": "Generate a production-grade TSDoc comment block for the selected function or interface:\n1. Provide a concise one-line summary followed by detailed behavioral context.\n2. Document all @param tags with accurate types and semantic descriptions.\n3. Document @returns specifying return types and conditions.\n4. Document @throws detailing every possible exception or failure scenario.\n5. Add a practical @example block demonstrating standard invocation.\n6. Format output strictly as a JSDoc/TSDoc block ready for direct insertion above the code."
    }
  }
}

Engineering Team Workflow and Best Practices

To extract the highest value from .vscode/cody.json, engineering organizations should integrate prompt management into standard software development lifecycles:

1. Treat Prompts as Code (PaC)

Prompts stored in .vscode/cody.json are code assets. When modifying prompt guidelines or adding new commands:

• Require Pull Requests and peer review before merging changes to main branches.
• Enforce JSON schema validation in pre-commit hooks or CI pipelines to avoid formatting errors that could break Cody extension parsing.
• Solicit feedback from developers across seniority levels to verify that generated code matches team style guides.

2. Practice Context Discipline

A common pitfall is setting "codebase": true on every command. While repo-wide context is essential for integration tests and multi-file architecture audits, it introduces significant network and parsing overhead for localized refactoring. Restrict "codebase": true to commands that legitimately need cross-file visibility, and rely on "selection": true for local logic transformations.

3. Progressive Evolution to the Sourcegraph Prompt Library

For large multi-repository engineering organizations, maintaining identical .vscode/cody.json files across dozens of distinct services can introduce synchronization drift. Sourcegraph introduced the Prompt Library (available in Sourcegraph Enterprise and Cody for VS Code v1.30+) as an evolution of custom commands.

Teams can start by standardizing their prompts in .vscode/cody.json to prove their value within an individual repository. Once refined, these templates can be promoted to the organization-wide Prompt Library in the Sourcegraph web UI. This centralized repository enables:

• Enterprise-wide prompt discovery and tagging.
• Admin-promoted prompts that appear prominently in Cody Chat.
• Dynamic @-mentions (@selection, @file, @repo, and web links) that execute consistently across both VS Code and JetBrains IDEs.

By grounding team prompts in version-controlled configurations today, engineering organizations establish a consistent quality baseline that elevates every engineer's productivity.

References

• Cody for VS Code v1.16: More powerful custom commands plus Claude 3 models as the new default
• Cody for VS Code v1.30: Introducing prompts and the Prompt Library
• Top 5 tips for using Cody with React
• Prompts - Sourcegraph docs