Skip to content
Frigg Docs

Workspace and file tools

Use these tools to establish repository scope and move from paths or result handles to bounded source evidence.

workspace

Section titled “workspace”

workspace reports the current session default, the known repository catalog, runtime status, and authoritative freshness. Calling it without arguments is a status read. Supplying path or repository_id adopts a repository for the session before returning status.

Parameter Required Default Meaning
path No — File or directory inside the repository to adopt.
repository_id No — Visible repository identifier to adopt.
set_default No true Make the adopted repository the session default.
resolve_mode No git_root git_root prefers the enclosing Git root; direct uses the supplied directory.

Compatibility aliases are accepted for resolve_mode: git, repo_root, and repo mean git_root; dir and directory mean direct.

Repository-aware tools resolve an omitted repository_id from the session default and then adopted repositories. A detached session can auto-adopt a sensible default, such as the only visible startup repository. Select a repository explicitly when more than one is plausible.

Important response fields:

  • repository and session_default describe the selected repository.
  • repositories[] is the runtime’s known visible catalog, with session and watcher state.
  • runtime.tools_exposed is the live public tool manifest.
  • freshness is the authoritative post-edit and index-readiness contract.
  • routing_stats appears only when local routing statistics are enabled.

The older top-level fields such as recommended_action, working_tree_dirty, changed_paths_since_snapshot, and watch_active are compatibility projections of freshness. See freshness and evidence for the decision model.

There is no public MCP reindex tool. When freshness directs you to rebuild, run the CLI frigg index intentionally.

list_files

Section titled “list_files”

list_files returns canonical repository-relative source paths.

Parameter Required Default Meaning
repository_id No session scope Restrict the listing to one repository.
path_regex No — Regex over repository-relative paths.
glob No — Repository-relative include glob.
language No — Source-language filter such as rust, php, or typescript.
path_class No — runtime, project, support, or any.
include_hidden No false Include hidden path segments.
limit No bounded server default Maximum rows in this page.
continuation No — Opaque token from completeness.continuation.

files[] contains repository_id, path, and size_bytes. Use completeness as the cardinality and paging truth. Legacy resume_from remains accepted, but do not send it together with continuation.

read_file

Section titled “read_file”

read_file reads the current live-disk contents of one canonical repository-relative path.

Parameter Required Default Meaning
path Yes — Canonical repository-relative file path.
repository_id No session scope Repository assertion or selection.
max_bytes No bounded server default Maximum returned bytes.
start_line No start of file First 1-based line.
end_line No bounded by request/server Last 1-based line.
line_count No bounded by request/server Number of lines from start_line.
presentation_mode No text text, json, or citation.
include_context_efficiency No false Include read-efficiency metadata; requires JSON presentation.

Presentation behavior:

  • text returns only selected source bytes as MCP text content, without structuredContent.
  • json returns path, line window, byte count, content, and optional efficiency metadata.
  • citation returns MCP text with 1-based LINE|content prefixes.

Use read_file when the path is already known or when you deliberately want current source rather than historical proof.

read_match

Section titled “read_match”

read_match reopens one row from a search, outline, or navigation response.

Parameter Required Default Meaning
result_handle Yes — Session-scoped handle issued by the producer.
match_id Yes — Row identity paired with that handle.
before No 10 Context lines before the match.
after No 10 Context lines after the match.
presentation_mode No text text, json, or citation.
include_context_efficiency No false Include efficiency metadata; requires JSON presentation.
origin No — Exact non-recursive producer request used only for stale-read recovery.

The handle is bound to the observed source revision. Frigg validates live content before returning bytes:

  • STALE_HANDLE: the handle expired, was evicted, or belongs to another session.
  • MIXED_HANDLE: the match_id does not belong to the supplied handle.
  • STALE_PROOF_ANCHOR: the source changed, disappeared, or can no longer be verified.

Frigg never substitutes current bytes for stale proof. Re-run the producer, then call read_match with the new handle. If you supplied origin, the error can include the exact producer retry in next_actions.

explore

Section titled “explore”

explore is a core tool for bounded iteration inside one known file.

Operation Required inputs Result
probe path, query Search the file and return structured matches.
zoom path, anchor Return a bounded source window around a 1-based span.
refine path, query, anchor Search only inside an anchor-derived window.

Shared optional inputs include repository_id, pattern_type, context_lines, max_matches, and include_context_efficiency. probe and refine support canonical continuation; legacy resume_from is accepted but cannot be mixed with it.

zoom defaults to text-first output and also supports JSON or citation presentation. probe and refine remain structured; presentation_mode=text is invalid for those operations.

Section titled “Related workflows”

Source Anchors

Section titled “Source Anchors”
  • ../frigg/crates/cli/src/mcp/types/repository.rs
  • ../frigg/crates/cli/src/mcp/types/workspace.rs
  • ../frigg/crates/cli/src/mcp/types/search.rs
  • ../frigg/crates/cli/src/mcp/types/target.rs
  • ../frigg/crates/cli/src/mcp/server/presentation.rs
  • ../frigg/crates/cli/src/mcp/server/workspace.rs
  • ../frigg/crates/cli/src/mcp/server/workspace_freshness.rs
  • ../frigg/crates/cli/tests/tool_handlers/proof_handle_producers.rs