Nix — 110 Operations for AI Agents

This page is the canonical reference an AI coding agent uses to refactor, query, and analyze Nix code through the act MCP server. 110 operations available: 36 refactor, 18 query, 42 analysis, 14 verification. Each operation is callable from Claude Code, Cursor, Codex, OpenCode, or any MCP-compatible agent host. Click any operation for a stable anchor link suitable for citation.

18Query

36Refactor

42Analysis

14Verify

Worked Nix examples

act101 parses Nix with the tree-sitter grammar and edits attribute sets, let bindings, and expressions as syntax nodes, so a binding change lands on the exact attrset or let it targets. It can convert an attr = attr; binding into the inherit attr; shorthand, give an inline import a name in a let binding, and extract a builtins.* call into a named let binding so the call's result gets a name instead of appearing inline. Each example below is the verbatim output of the command shown, run against the file shown.

Convert a redundant binding to inherit shorthand

pkg.nix writes src = src; inside an attrset alongside name and version, instead of the concise inherit form.

$ act refactor-lang convert_to_attr_set_shorthand --file pkg.nix --params '{"attr_name":"src"}'

Before

{ name = "pkg"; src = src; version = "1.0"; }

After

{ name = "pkg"; inherit src; version = "1.0"; }

src = src; becomes inherit src;, leaving name and version untouched.

Name an inline import with a let binding

default.nix is a development shell: mkShell gets ripgrep and shellcheck, and its shellHook calls import ./tools/motd.nix inline with pkgs.

$ act refactor-lang convert_import_to_let_binding --file default.nix --params '{"import_path":"./tools/motd.nix","binding_name":"motd"}'

Before

{ pkgs ? import <nixpkgs> { } }:

pkgs.mkShell {
  packages = [ pkgs.ripgrep pkgs.shellcheck ];
  shellHook = (import ./tools/motd.nix) { inherit pkgs; };
}

After

let
  motd = import ./tools/motd.nix;
in
{ pkgs ? import <nixpkgs> { } }:

pkgs.mkShell {
  packages = [ pkgs.ripgrep pkgs.shellcheck ];
  shellHook = (motd) { inherit pkgs; };
}

A let motd = import ./tools/motd.nix; in now wraps the whole file, function head included, and shellHook calls (motd) with the same argument.

Extract a builtins call into a let binding

release.nix reads its pinned revisions with builtins.fromJSON (builtins.readFile ./pins.json), nested inside the lib.mapAttrs call that turns them into flake references.

$ act refactor-lang extract_builtin_call --file release.nix --params '{"builtin_call":"builtins.fromJSON (builtins.readFile ./pins.json)","binding_name":"pins"}'

Before

{ lib }:

{
  channel = "stable";
  pinned = lib.mapAttrs (name: rev: "github:example/${name}/${rev}") (builtins.fromJSON (builtins.readFile ./pins.json));
}

After

let
  pins = builtins.fromJSON (builtins.readFile ./pins.json);
in
{ lib }:

{
  channel = "stable";
  pinned = lib.mapAttrs (name: rev: "github:example/${name}/${rev}") (pins);
}

The whole call, inner builtins.readFile included, moves into let pins = …; in, and lib.mapAttrs now takes (pins). The builtin_call parameter is matched against the whole call as written, not against the function name alone.

Query

18 query tools, the same on every supported language. Descriptions live in the shared reference: /docs/query-tools.

callers control_flow data_flow definition diagnostics effect_closure effect_summary fix_auto get_type graph import_organize interface mutations references repo_outline skeleton symbols symbols_batch

Refactor

Operation	Description
`add-inherit-statement`	Add an `inherit` statement to an attribute set for given variables
`convert-boolean-to-if`	Convert a boolean expression into an if-then-else expression
`convert-if-to-boolean-expression`	Simplify `if x then true else false` to just `x`
`convert-import-to-let-binding`	Convert an inline `import ./file.nix` into a let binding
`convert-lambda-to-function`	Wrap an anonymous lambda in a named let-bound function
`convert-rec-to-scope`	Convert `rec { ... }` to a `let...in` expression
`convert-string-concat-to-interpolation`	Transform string concatenation expressions to Nix string interpolation
`convert-to-attr-set-shorthand`	Convert attr = attr; bindings to inherit form
`convert-to-string-interpolation`	Convert string concatenation (+ operator) to Nix string interpolation
`extract-builtin-call`	Extract a repeated builtins function call into a named let binding
`extract-function`	Extract an expression into a new named function binding
`extract-function-from-lambda`	Convert an anonymous lambda into a named function binding
`extract-let-binding`	Extract an expression into a let-in binding
`extract_function`	Extract a code selection into a new function — automatically infers parameters, return types, and inserts the call site. Use instead of manually cutting/pasting code. Works without LSP; LSP improves type inference. Params: file (string), new_name (string), start_line (u32), start_column (u32), end_line (u32), end_column (u32) [, preview (bool), receipt (bool)]
`extract_variable`	Extract an expression into a named variable — inserts the declaration and replaces the expression with the variable name. Works without LSP. Params: file (string), new_name (string), start_line (u32), start_column (u32), end_line (u32), end_column (u32) [, preview (bool)]
`generate-attribute-set`	Generate an empty or structured attribute set
`generate-filter-function`	Generate a `filter` operation skeleton over a list
`generate-fold-operation`	Generate a `builtins.foldl'` operation skeleton
`generate-function`	Generate a new function binding skeleton in Nix
`generate-if-then-else`	Generate complete if-then-else structure
`generate-let-binding`	Generate a let-in expression with variable and body
`generate-map-function`	Generate a `map` operation skeleton over a list
`generate-mkderivation`	Generate mkDerivation skeleton with common attributes
`generate-test-scaffold`	Generate a test expression scaffold for Nix code
`inline`	Inline a variable, function, or method — replace every usage with its definition body, then remove the original. The inverse of extract. Works without LSP: it walks the workspace for references and refuses, naming the file, when it cannot read every candidate file; a language server makes the reference set exact. Params: file (string), symbol (string) [, line (u32), column (u32), preview (bool), receipt (bool)]. line alone resolves the symbol's one declaration on that line (refused when the line declares none or several of the name); line + column pinpoints its name
`inline-function`	Inline a function binding by replacing calls with the body
`inline-variable`	Inline a let-bound variable by replacing uses with its definition
`insert_body`	Replace a function's implementation body with new code. AST-validated — rejects if the result has parse errors, so you can't accidentally break syntax. Use instead of manual text editing for function rewrites. Params: file (string), symbol (string), code (string) [, commit (bool)]
`move_symbol`	Move a function, class, or type to a different file and automatically update all imports across the codebase. Use instead of manually cut/paste + fixing imports. Works without LSP: it walks the workspace for references and refuses, naming the file, when it cannot read every candidate file; a language server makes the reference set exact. Params: file (string), symbol (string), destination (string) [, preview (bool), receipt (bool)]
`organize-imports`	Sort the import bindings of each let and attribute set to the top of the set
`recipe_run`	Run a codemod recipe: declarative match → transform → optional verify across modeled grammars. Preview lists matches; apply writes with optional E7 receipts and all-or-nothing rollback. Returns a per-site report.
`remove-unused-parameter`	Remove a named parameter from a function's formal set
`remove-unused-variable`	Remove a let binding that is never used
`rename`	Rename a symbol and automatically update ALL references across the codebase. Safer and faster than find-and-replace — AST-aware, won't rename strings or comments. Works without LSP: it renames across the workspace and refuses, naming the file, when it cannot read every candidate file; a language server makes the reference set exact. Params: file (string), old_name (string), new_name (string) [, line (u32), column (u32), preview (bool), receipt (bool)]. line alone resolves the symbol's one declaration on that line (refused when the line declares none or several of the name); line + column pinpoints its name
`rename-identifier`	Rename a Nix binding and the references that resolve to it
`reorder-function-arguments`	Reorder formal parameters in a function definition

Analysis

42 analysis tools, the same on every supported language. Descriptions live in the shared reference: /docs/analysis-tools.

analyze_api_diff analyze_chokepoints analyze_clones analyze_clusters analyze_cohesion analyze_conformance analyze_coupling analyze_cycle_risk analyze_cycles analyze_dead_code analyze_depth analyze_entry_points analyze_export analyze_extraction analyze_fan_balance analyze_features analyze_hotspots analyze_impact analyze_inconsistencies analyze_inheritance analyze_interface_bloat analyze_interfaces analyze_layers analyze_orphan_types analyze_patterns analyze_platform_deps analyze_readiness analyze_roles analyze_seams analyze_stability analyze_surface analyze_test_gaps analyze_thickness analyze_type_completeness churn_hotspots co_change_clusters coverage_overlay ownership_map profile_overlay simulate split_module trace_overlay

Verify

14 verify tools, the same on every supported language. Descriptions live in the shared reference: /docs/verification.

bisect_regression gate generate_test_harness scan secret_surface summarize_pr taint_flow unsafe_surface verify_behavioral_equivalence verify_contract_preserved verify_diff_semantics verify_port_parity verify_side_effects verify_test_impact

← NinjaNoir →