Skip to content

AGENTS.md

Latest commit

 

History

History
72 lines (50 loc) · 3.59 KB

AGENTS.md

File metadata and controls

72 lines (50 loc) · 3.59 KB
Raw

AGENTS.md

This file provides guidance to agents when working with code in this repository.

Overview

This repository provides command completion signatures ("specs") for Warp terminal. It contains two Rust crates:

  • warp-command-signatures: The main library that embeds and exposes command specs. Used as a dependency by the main warp app.
  • warp-completion-metadata: Core types for signatures, arguments, options, generators, and the Fig-compatible JSON schema.

Repository-level agent skills are located in .agents/skills/. These provide specialized workflows for working with this codebase. Always use these skills when creating or editing command completion signatures.

Architecture

Command Specs (JSON)

Specs are JSON files based on the Fig completion spec schema, but Warp does not use Fig's JavaScript generators. Instead:

  • The generatorName field references Rust-based generators (see below)
  • Fig's generateSpec JavaScript field is present in some imported specs but is ignored by Warp
  • Static suggestions, templates (filepaths, folders), and subcommand/option definitions work as documented
Location Description
command-signatures/json/*.json Hand-written specs
command-signatures/json/autogenerated/powershell/*.json Auto-generated PowerShell cmdlet specs
command-signatures/json/overrides/powershell/*.json Hand-written overrides for autogenerated specs

The assets.rs module uses rust-embed to flatten these directories into a single namespace at compile time, so callers just use signature_by_name("git").

Generators (Rust)

Generators produce dynamic completions by running shell commands. They are defined in command-signatures/src/generators/ (one file per command or command family).

A generator consists of:

  1. A GeneratorProcess (either a static CommandBuilder or a function that builds a command from tokens)
  2. An on_complete_callback that parses the command output into Suggestions

JSON specs reference generators via the generatorName field (e.g. "generatorName": "branches"). The mapping from name → Rust code is established in generators/mod.rs via dynamic_command_signature_data().

Example from brew.rs:

CommandSignatureGenerators::new("brew")
    .add_generator(
        "formulae_generator",  // Referenced in JSON as "generatorName": "formulae_generator"
        Generator::script(CommandBuilder::single_command("brew list -1"), |output| {
            output.trim().lines()
                .map(|line| Suggestion::with_description(line, "Installed formula"))
                .collect_unordered_results()
        }),
    )

Override System

For autogenerated specs (currently PowerShell only), hand-written augmentations live in json/overrides/. Overrides are matched by option name or argument index and merged at generation time. Only template and generatorName fields are currently supported for overrides.

Key Types

  • Signature: Defines a command/subcommand (name, options, arguments, subcommands)
  • Argument: A positional parameter with types (Template, Generator, or literal Suggestion)
  • Opt: A flag/option with optional arguments
  • Generator: Produces dynamic suggestions by running shell commands
  • Template: Built-in generators for files/folders

Testing Invariants

Tests in lib.rs verify:

  • All GeneratorNames referenced in specs exist in dynamic_command_signature_data()
  • All JSON specs deserialize without error
  • Generator commands contain no unsafe (unquoted) newlines (required for TMUX control mode)