Skip to main content

Overview

Tool group

Legacy stored bot toolsets that still name git_action as the group are rewritten to git_and_file_tools automatically on startup.

Tools in this group

Purpose

The git_and_file_tools group covers repository file operations and Git version control. Use file for anything that reads or changes file content; use git_action for version control, not for reading files. The group also includes document text extraction (PDF, Word, PowerPoint, Google Slides, scans via OCR) and Markdown-to-PDF conversion. See Cost accounting for OCR-request metering. The git_action tool provides Git workflows for content your data agents create. It supports branching, diffs, and history, and can auto-register saved files so they are immediately available to other tools and entities across the platform. repo_id accepts a local clone id, a remote org/name reference (for example org/repo), or a full remote URL; Genesis resolves remote references to the visible local clone when one exists.
In container-based deployments, Genesis prepares the mounted Git workspace on startup by ensuring repos/, worktrees/, and .genesis_runtime/ exist under GIT_PATH (default /app/bot_git) and by configuring Git trust for the shared volume. That keeps git_action workflows working on reused persistent mounts without manual setup.
When durable Git is enabled in a Databricks App, git_action commits and ref changes are persisted through the configured volume and Lakebase backend. See Durable git repositories in the Databricks App pilot for setup and restore behavior. file restore behavior. In a Databricks App, and wherever Genesis runs as root (Snowflake, EKS and self-hosted Docker), agent Git refuses repositories whose local or worktree configuration contains settings outside Genesis’s safe allowlist, or that have submodules. Before each Git operation on an existing repository, Genesis checks its configuration with up to three read-only Git subprocesses. Git then runs with hooks and fsmonitor switched off; repository configuration that could run filters, drivers, helpers, an SSH command, or other commands is rejected rather than executed. Configuration the operator sets at system or global scope, or in the server’s environment (an SSH command or SSH agent, credential helpers, http.* and url.* settings), still applies. If a check cannot complete, the operation is also refused. Remove unsupported repository settings or submodules before retrying. Repositories that need Git LFS or other custom filters, merge or diff drivers cannot be used by agent Git there: Genesis does not install git-lfs, filter configuration in a repository is refused, and hooks (including LFS’s pre-push) do not run. This applies to Git Browser, Blueprint repository operations, and agent workflows that write managed Apps, skills, dashboards, mission repositories, or Bitbucket checkouts. dbt’s run_git_command is unavailable in the App; see DBT Cloud Tools. When a remote Git operation uses credentials from a saved Git connection, Genesis passes them to the Git process through its environment rather than its command line or remote URL. Clones keep those credentials out of the remote URL stored in .git/config.
In demo mode (demo.enabled), Genesis blocks remote Git and GitHub/GitLab actions such as pull, push, fetch, list_remote_repos, create_pull_request, and credential-storage actions. Local repo workflows (read, commit, branch, diff) still work. Set demo.allow_remote_git to true on trusted demo instances to lift this block — see Advanced Settings.

Key Features & Functions

File Operations and Diffs

Read and write repository files, inspect content at arbitrary refs, generate diffs, and apply unified patches.

Commit and Branch Management

Create branches, switch context, commit changes, and keep work isolated.

History and Status Tracking

Inspect commit history and working tree status to audit changes.

Save and Register Workflow

Use a single call to save a file from disk into Git and auto-register and attach it.

PDF Parsing

Extract text and metadata from PDFs in your repo or by path.

Input Parameters for Each Function

git_action

Parameters Action names are trimmed and matched case-insensitively. For example, LIST_REPOS and list_repos both invoke list_repos. Action-specific fields For example, create a restricted clone and grant a role read access:
The result’s scope is the stored scope and access summarizes who can use the clone. If it includes access_warning, pass the warning to the user. For the Git Browser’s access dialog and connection-specific defaults, see Git Browser.

Repository access

get_repo_access reads the repository’s scope, owner and role grants, along with the last access change and whether the person in the turn may change it. It requires view access. set_repo_access changes the same record as Git Browser’s Manage Access control; it acts on the source repository even when the Git tool uses working copies.
A change is authorized for the signed-in person behind the turn, not the agent: an admin, repository owner, manage_git holder (except on another person’s personal repository), or someone with a manage role grant on a restricted repository may change it. Changing ownership to another user requires manage_git. Switching to shared or personal clears role grants; an inherited repository must be changed at its blueprint or mission. Changes run under Action Review (repository.access.v1): with no tenant rule for this action, it runs immediately; a pending or denied review does not apply the change. The response includes before and after records; if the result says the write was not confirmed, read the record with get_repo_access before deciding what to do next. Cost: reading access performs a repository-record read, an audit query and authorization reads. A change also loads policy, writes the RBAC record and creates audit rows.
For GitHub PR comments and code reviews, use github_connector actions in GitHub Connector Tools. The GitHub-specific git_action PR/MR operations continue to support PR and MR management on GitHub and GitLab.
Prefer action: save_file with auto_register: true to save to Git and automatically register and attach the file in one step.
clone_repo can check out a non-default branch during clone with branch_name. Unless you override them, shallow and single_branch both default to true; set depth=0 to request full history.
When clone_repo reuses an existing clone, Genesis fetches its remote’s default branch before handing it out, unless that clone was successfully fetched within the last two minutes. A clean, idle clone on that branch is fast-forwarded; a dirty, busy, or differently branched clone is left in place. The response’s freshness explains whether it is current, how many remote commits it may lack, how many local commits the default branch lacks, or why Genesis could not tell; ahead_by reports the latter count. A checkout with local commits that are not on the remote is never described as up to date. A failed or timed-out fetch does not prevent the hand-out and leaves the checkout unchanged. Configure the throttle and timeout with git_clone_reads.
For non-reserved repositories, mode is derived from the repository itself: a .git entry means the repository is Git-backed, while a repository without one is storage-only. Reserved storage-only repository IDs remain storage-only even if a .git entry exists. create_repo defaults to repo_type="storage"; pass repo_type="git" to initialize a Git-backed repository. set_repo_mode(repo_mode="git") upgrades a storage repository by initializing Git metadata. set_repo_mode cannot downgrade a Git-backed repository to storage-only; repo_mode="storage" is accepted only as a no-op when no .git entry exists. To stop using Git, delete the repository and recreate it with repo_type="storage". Newly initialized Git repositories start on the main branch.
list_repos returns the whole visible listing when limit and cursor are omitted. To page the listing, pass a positive integer limit (capped at 200), then pass the returned pagination.next_cursor as cursor with the same pattern. The pagination block reports page_size, returned, total, has_more, and next_cursor. Cursors are signed and bound to the requesting user and agent, so do not reuse one across callers or agents. A cursor issued before signed cursors were introduced is expired; omit cursor to start the listing again. Any invalid cursor or limit returns an error instead of a partial page.
Parallel workstreams: reuse to read, branch to edit. With git_worktrees.enabled set to true (default false), a person reads a remote repository through their own private copy, created the first time they use that remote by a full clone. Other people have their own copies. If a repository is busy, Genesis refuses the change after git_worktrees.lock_wait_seconds (default 30) rather than waiting longer. For HTTPS GitHub and GitLab downloads, git_worktrees.download_stall_seconds (default 120) sets the low-speed timeout; see Git Worktrees configuration for the HTTPS and SSH behavior. Before the first edit, call git_action(action="prepare_edit", repo_id="org/repo", title="what you are changing"). When the conversation has no branch yet, the first call asks the user in a chat card where the edits should go: a fresh branch from the fetched default branch, one of the user’s existing work branches, or a branch from another remote branch. The fresh-branch name is editable. Pass branch_name when the user names a preferred branch; it becomes the card’s suggested name and default when valid. If the name cannot be used, Genesis keeps the generated default and returns branch_name_note with the reason. An existing branch for this conversation is kept rather than renamed or duplicated, and an already-answered card keeps its selected branch. An unanswered offer waits for git_worktrees.edit_choice_wait_seconds (default 60); while git_worktrees.enabled is on, a sweep runs every 15 seconds and applies the default after that wait. If the user sends a message instead of answering, call prepare_edit again to apply the default. If no chat card can be raised, the default starts immediately. After an answer, call git_action(action="open_edit", request_id="...") with the returned request ID. It returns the branch for this conversation. Use the returned repo_id for edits, commits, and pushes, and the returned plain branch name for branch actions. In a shared conversation, the answered card resumes the turn as the person it asked, not the conversation owner. If Genesis cannot establish who asked for the edit, it refuses the write with EDITING_FOR_SOMEONE_ELSE rather than applying it to another person’s branch. A shared clone remains read-only: reads, fetch, and a fast-forward pull of its default branch are supported. On the conversation’s branch, reads, file edits, create_branch, switch_branch, commit, push, and fetch are supported; other actions return NOT_SUPPORTED_ON_A_BRANCH_YET. A repository without a remote is read-only while this setting is on. A fetch that exceeds git_worktrees.fetch_timeout_seconds (default 120, minimum 5) does not start a branch. See Git Worktrees configuration.With the setting off, the existing clone_repo flow remains: it reuses a visible clone for reading, and isolated=true requests this thread’s own editable copy. If another workstream has a clone in use, Genesis does not hand it over; use an isolated copy or read a branch by ref after fetch(branch_name=...). Use fetch_more_history for older history; do not invent a repo_id or reclone for history or a branch.
Auto-switch to default branch on first read. On the first repo-scoped content read in a thread session — file(action="read", "list", "find", or "fast_search") and git_action(action="search") or "grep" (and file(action="search"), which delegates to git_action) — Genesis may automatically switch a local clone from a non-default branch back to the repository default branch when the working tree is clean. Successful responses can include _auto_branch_switch with auto_switched: true (from_branch, to_branch, message) or auto_switch_skipped: true with a reason. Auto-switch runs once per thread/session/repo key and is skipped when you already called git_action(action="switch_branch") in the same session, when HEAD is detached, when the clone is already on the default branch, when Genesis cannot verify status, or when the working tree is dirty. A dirty tree includes modified, staged, or conflicted files and user-owned untracked paths. Genesis internal metadata (.genesis/, .genesis-sync.lock, .genesis-sync.lock.lock) remains ignored, except for the user-authored .genesis/dbt-version runtime declaration. When skipped for a dirty tree, reason is dirty_working_directory. Managed remote WIP worktrees are preserved — auto-switch does not run when browsing a resolved WIP branch. If a remote repository has no local default branch, Genesis creates a local tracking branch from origin/<default-branch> before switching; if it cannot, it stays on the current branch and reports reason: "default_branch_not_made". For a repository with no remote, Genesis resolves its default branch from local branches: it prefers main, then master, and otherwise uses the branch when exactly one local branch exists.
For git_action(action="push") and git_action(action="pull"), omitting branch_name targets the current branch. Push uses an explicit refspec and sets upstream tracking, so a newly created local branch can be pushed or pulled without a prior git push -u. On a detached HEAD, Genesis returns error_code="git_no_upstream_branch" and asks you to pass branch_name. When Git itself reports a missing upstream, the normalized error includes remediation.action="set_branch_name" with the same guidance.
Every agent commit, merge commit, and file write with a commit_message names the person who asked for the change in one trailer line, chosen by the connection’s git_requester_credit setting; see Crediting the person who asked. git_action(action="commit") also accepts optional co_authors, an array of strings such as ["Jane Doe <[email protected]>"]. Genesis appends each entry as a Co-authored-by: trailer, skips duplicates already present in the commit message, and drops an entry naming the person already credited.
The primary author for commit can come from the repo’s configured connection or, when none is set, from the caller’s scoped default GitHub or GitLab connection. On GitHub, GitLab, and Bitbucket connections, git_author_mode controls that identity. Use custom together with git_author_name and git_author_email when you need a fixed verified author identity. If no connection author override is resolved, Genesis uses the agent’s display name and the configured GIT_USER_EMAIL; when no email is configured, it leaves the address blank rather than inventing one. Commits made later through GitFileManager re-resolve the author, including the noreply address of a GitHub App’s bot or of a bot account that owns the token; a person’s own token leaves the address blank, with a notice.
git_action(action="commit", dry_run=True) previews what a commit would contain without mutating the repository. Genesis does not run git fsck, auto-fetch, staging, or the commit itself on this path — it returns a read-only preview with dry_run: true, path lists such as already_staged, would_stage, would_commit, changed_files, untracked_files, and conflicted_files, a diff_summary object with counts, can_commit, and preview_exact. When check-in transforms or unsupported worktree entry types make the preview uncertain, uncertainty lists affected paths and a reason. commit_message (or message) is still required. Pass stage_paths to preview selective staging; omit files — that parameter is only valid for create_files_bulk. On failure, responses can include error_code values such as GIT_PREVIEW_STATE_CHANGED, GIT_REPOSITORY_INVALID, GIT_STAGE_PATH_INVALID, or REPO_NOT_INITIALIZED, and may list unmatched_stage_paths or rejected_stage_paths when staging would fail.
Before a real git_action(action="commit") (when dry_run is false or omitted), Genesis validates the local clone with git fsck. When damage is confined to loose object files that nothing refers to — neither committed history nor the staging index — and reachable history still walks cleanly, the commit proceeds. The response can include integrity_warnings, damaged_object_paths, and an integrity_hint that suggests git_action(action="quarantine_corrupt_objects", repo_id="...") to move the stray objects aside. This applies to local-only repos with no remote as well as remotes — a single damaged unneeded object no longer blocks every commit. Pack corruption, damage in committed history, damage to a staged blob the index still needs, and other fsck failures that are not confined to unneeded loose objects still block the commit. Committing while a staged blob is unreadable would capture the wrong file contents with no error, so Genesis blocks that case. When blocking corruption is detected, Genesis can automatically rebuild the checkout from its configured remote and retry the commit when all of the following are true: a remote is configured, the checkout is not a managed worktree, and there are no unpushed commits on the upstream tracking branch. A successful rebuild sets auto_healed: true on the commit response. When auto-heal is skipped or fails, the response includes error_code: GIT_REPOSITORY_CORRUPTED, validation, recovery_options, and auto_heal_attempted (no_remote, managed_worktree, unpushed_commits, or rebuild_failed).
git_action(action="quarantine_corrupt_objects") moves damaged loose objects out of the object store into a timestamped directory under genesis_quarantine/ inside the git directory. Files are moved, not deleted, so they remain available for inspection. Genesis only quarantines when git fsck names specific loose object paths, nothing in the repository refers to the damaged objects (not committed history and not the staging index), reachable history is intact, and the damage is not in a pack file. Successful responses include message, quarantined, quarantine_dir, and repository_valid_after. When some paths cannot be moved, the response can include skipped with per-path reason values. When a damaged object is still referred to, Genesis refuses to move it and returns error with needed_object_ids, staged_files_for_needed_objects (object id to staged path), and fsck_output. If every needed object is staged from a working-tree file, recovery_options can recommend restore_object_from_working_tree: delete the damaged object file and stage that file again so git rewrites the object with the same id. That repair needs filesystem access agent tools do not have today — an operator with a shell can run it. Other failures return error and may include fsck_output or fsck_output_after when fsck still reports problems after the move.
The secret scan for a real commit ignores the exact XML namespace URLs used by Talend designs: http://www.omg.org/XMI, http://www.w3.org/2001/XMLSchema-instance, http://www.talend.org/mapper, and http://www.talend.org/properties. It also ignores the scheme of HL7 terminology identifiers on hl7.org/fhir/ValueSet, hl7.org/fhir/CodeSystem, hl7.org/fhir/NamingSystem, hl7.org/fhir/sid, and terminology.hl7.org/ValueSet, terminology.hl7.org/CodeSystem, or terminology.hl7.org/NamingSystem paths. The identifier host and path remain scanned for potential secrets; URLs with a port, credentials, query, fragment, or URI parameters do not qualify for this exception. Other content in the staged changes is still scanned for potential secrets. The scanner also recognizes URLs with repeated JSON-escaped slashes and uppercase HTTP or HTTPS schemes, so escaping or scheme case does not hide a credential or insecure URL. If a real commit is refused with error_code="SECRETS_DETECTED", confirm with the user that each finding is not a real secret, then pass its id in allow_secrets, for example allow_secrets=["<finding-id-from-refusal>"]. The override covers only the IDs named; findings added by a later commit are refused again, and true overrides nothing.
Genesis serializes git index mutations — staging, committing, deleting, and similar writes through git_action and file — per resolved git directory so concurrent agent threads in the same server queue instead of racing for index.lock. Staging runs a subprocess git add with an explicit working directory instead of GitPython’s index add, so concurrent repo operations do not temporarily change the process-wide working directory. When another process still holds the lock, Genesis retries the mutation up to three times with a short backoff and may clear an abandoned lock file that has been present for at least 60 seconds. If a lock error still blocks the operation after those retries, the response includes lock_detected: true, a recovery_action pointing at git_action(action="force_unlock", repo_id="..."), and a recovery_hint. Use force_unlock only when you are sure no live git process still owns the lock — it removes index.lock immediately with no age check. Lock paths follow linked worktree gitdir: pointers, so managed per-user worktrees are covered.
For Bitbucket pull calls, Genesis passes user.name and user.email on the Git command automatically. Override those values with GIT_USER_NAME and GIT_USER_EMAIL; when unset, Genesis uses Genesis Bot as the name and uses the configured GIT_USER_EMAIL or leaves the email blank.
Do not use git_action or file to edit blueprint_manifest.yaml. Use create_blueprint(action="CREATE_BLUEPRINT_FROM_THREADS", ...) for new blueprints, create_blueprint(action="PREVIEW_EDIT", blueprint_name="...", edit_operations=[...]) for targeted deterministic updates, and create_blueprint(action="APPLY_EDIT", preview_id="...") after review. Use change_description only when the requested edit cannot be expressed as structured operations, and keep blueprint phase definitions in the single manifest file instead of splitting them across YAML includes or $ref patterns.
For git_action(action="list_repos", details=True), each entry in details includes mode, has_git_dir, has_remote, scope, owner_user_id, owner_bot_id, and undeletable. When a repo has a remote, Genesis also returns a credentials-redacted remote_url, and clone_source is set when the remote host can be inferred as github, gitlab, bitbucket, or azure_devops. Set include_paths to true to add path. When RBAC hides repos from the caller, the response can include hidden_by_access_count. mode reports the repository’s effective mode, so a reserved storage-only repository can report mode: "storage" even when has_git_dir is true; has_git_dir reports the physical .git entry independently. For remote-clone grouping and duplicate fields, see Output.
For repo-scoped git_action calls, repo_id accepts the local clone id, a remote org/name reference, or a full remote URL. Genesis resolves remote references to the visible local clone when one exists. Successful responses can include resolved_from, matched_by (local_repo_id or remote_identity), and resolved_repo_id. If no visible clone matches, Genesis returns error_code="REPO_REFERENCE_NOT_FOUND" with guidance to inspect clones via list_repos(details=True), clone with clone_repo, or verify the remote with check_remote_repo_exists. When multiple clones match, Genesis returns error_code="REPO_REFERENCE_AMBIGUOUS" with a candidates list — retry with an explicit local repo_id.
Actions that open or change a local clone check the caller’s repository access before reading its contents or changing it. A caller without access cannot use these actions to discover another user’s personal or restricted repository.
The shared uploads repository is scoped by conversation access. git_action and file calls can list, search, or read only conversation folders the caller may open; operations that reach another conversation’s folder are refused.

Remote connection resolution

When a remote Git workflow omits connection, Genesis first uses any saved connection already associated with that repo remote. If no repo-specific connection is stored, Genesis falls back to the effective default saved connection for that platform for the current caller. Effective defaults follow the same Connections precedence used in the UI and API: My default, then a matching Role default. There is no workspace-wide system default fallback, and Genesis does not treat a sole visible connection as an implicit default. See Default connection layers. If multiple matching role defaults point at different Git connections and Genesis cannot choose one, remote actions return error_code="AMBIGUOUS_ROLE_DEFAULT_CONNECTION" together with matched_roles and matched_role_defaults. Set a personal default or pass connection explicitly to continue. When an agent starts a user’s new remote download without an explicit connection, Genesis prefers that user’s matching personal Git connection: the user’s default when it matches the remote, or their only matching connection. Genesis uses it only if it can reach the remote. If there are multiple personal matches without a matching default, the personal connection cannot reach the remote, or the connection listing/default cannot be read, Genesis falls back to the team’s shared connection when available and tells the user why. Branches keep the connection pinned to their source download; Genesis does not silently switch existing branches to a different Git identity. An editing branch keeps the connection its source download was made through. If that download has no recorded connection, Genesis carries one forward only when the remote’s shared clones agree on the same shared connection. Naming a different connection for the branch’s remote operation is refused with error_code="CONNECTION_IS_PINNED"; continue with the connection attached to the branch instead. git_action(action="check_stored_credentials") and the multi-platform check_all_stored_credentials scan resolve the caller’s scoped default for each platform (github, gitlab, bitbucket, azure_devops). When role defaults conflict, those checks return error_code="AMBIGUOUS_DEFAULT_CONNECTION" with an explicit error instead of reporting “not configured”. For git_action(action="get_tag_info"), pass repo_id and tag_name to read a tag from an existing local clone. If that tag is absent and the clone has a remote, Genesis falls back to the provider lookup; include repo_name (and owner or workspace, as required by the provider) to request a remote lookup directly. A missing local clone with only repo_id returns NO_LOCAL_CLONE rather than creating a clone or calling a provider without a repository name. When the tag is absent and the local clone has no remote, the response is TAG_NOT_FOUND_NO_REMOTE.

Read at a Ref

Use show, ls_tree, and diff when you need to inspect Git state at a branch, tag, SHA, or Git expression without switching branches or merging. show displays what a file looks like at a ref, bounded by max_chars — it is not a file-reading mechanism. To read file content with line windows, byte ranges, or search, use file(action="read"). For managed remote artifact repos where you only need a branch file read, prefer file(action="read", branch_name="..."); use git_action(action="show") for quick ref previews on non-managed remotes and arbitrary refs.
These actions read from the local clone’s refs. Run git_action(action="fetch", repo_id="...") first if you need the remote state to be current. show, ls_tree, and diff do not auto-fetch.

Show File Content at a Ref

show returns content with encoding="utf-8" for valid UTF-8 text, or encoding="base64" plus binary=true for binary files and complete files that are not valid UTF-8. This preserves invalid or incomplete trailing bytes rather than returning lossy text. Successful responses also include resolved_ref, branch_name, commit_sha, sha, size, truncated, and max_chars. branch_name is the branch the content came from — null when the ref is a tag, a SHA, an expression, or HEAD is detached. Check it before treating the content as canonical: an omitted ref reads the checked-out branch, which is not necessarily the default branch. Content is clipped to max_chars (default 2000); when clipped, truncated=true and truncation_notice explains how to read more. For file content with line windows or byte ranges, use file(action="read") instead of show.

List a Tree at a Ref

ls_tree returns entries with mode, object_type, sha, and path. object_type can be blob, tree, or commit for submodules. Responses also include branch_name (same meaning as for show), plus truncated and max_entries; truncated=true means the listing was clipped to max_entries.

Diff Refs

from_ref is required for diff. For create_branch, it is an optional start point (default: HEAD). Omit to_ref to diff against the working tree. With name_status=true, Genesis returns name_status_entries such as {"status": "M", "path": "src/app.py"}, and rename or copy rows can also include old_path. Patch output uses patch, supports max_chars (default 200000), and sets truncated=true when the diff is clipped.

Create Branch

Use reset_if_exists=True for bot or flow work branches that are recreated from a remote default branch on every run — for example after a prior run squash-merged the branch and left the local checkout pointing at stale history. Genesis refuses the reset when the working tree has uncommitted changes.

Delete Branch

Delete a local branch after a workstream is complete. By default, Genesis refuses to delete an unmerged branch; set force=True to use Git’s force-delete behavior instead.
delete_branch always refuses to delete the checked-out branch or the repository’s default branch. Set delete_remote=True only when the branch should also be removed from origin; the remote deletion uses the resolved Git connection.

Azure DevOps Remote Workflows

Use the existing remote-repository and pull-request actions with platform="azure_devops" or an Azure DevOps connection.
Azure DevOps remote discovery and PR routing support the canonical Azure DevOps Services HTTPS host dev.azure.com, the SSH host ssh.dev.azure.com, and legacy *.visualstudio.com clone URLs.

Create Pull Request with an Explicit Base Branch

For create_pull_request, target_branch sets the branch the pull request merges into (the base or destination branch). It works on GitHub, GitLab, Bitbucket, and Azure DevOps for regular cloned repos. When omitted, Genesis uses the repository’s default branch. Use it to open a PR against a long-lived integration branch instead of main/master, or when automatic default-branch detection picks the wrong branch. base_branch is an accepted alias for target_branch. If both are supplied, target_branch wins. Whitespace-only values are ignored and fall through to the repo default.
Managed-artifact sources (skills, flows, apps, and agents registered via Remote Repositories) currently still target their own default branch when you call create_pull_request; target_branch does not override that behavior on those repos.

Create a Draft Pull Request or Update an Existing Pull Request (GitHub, Bitbucket Cloud)

Set draft=true on create_pull_request to open a GitHub pull request as a draft. It defaults to false; other platforms and managed-artifact worktrees refuse draft creation. GitLab reuses an open merge request for the same source branch without changing its title or description; GitHub refuses a duplicate open pull request and identifies its number. Use update_pull_request to change an existing GitHub or Bitbucket Cloud pull request’s title or description. Bitbucket Server and Data Center, GitLab, and Azure DevOps do not support this update.
Pass title, body, or both to update_pull_request; an omitted field stays unchanged, while body replaces the whole description. Read the current description first and pass its digest as expected_body_sha256 whenever you send body. GitHub returns the digest at info["data"]["body_sha256"]; Bitbucket Cloud returns it at info["body_sha256"]. If the description changed after the read, the update is refused so you can reread and apply your edit to the current text. Title-only updates need no digest. GitHub also permits edits to closed or merged pull requests; Bitbucket Cloud permits edits to open pull requests only. Updates run under Action Review. On Bitbucket Cloud, Genesis reads the pull request again before its PUT and refuses a description that changed since approval; Bitbucket does not provide a conditional PUT, so an edit made between that final read and write can still be overwritten.
See GitHub Connector Tools — Output for the metadata and CI error details returned by get_pull_request_info. Reading pull-request information with get_pull_request_info and inspecting structured data with file(action="inspect_structured_data") require repository view access, not edit access. Mutations still require edit access.

Merge a pull request (GitHub, Bitbucket Cloud)

merge_pull_request runs under Action Review because merging cannot be undone. Its preview uses dry_run=true to return the pull request’s get_pull_request_info without merging or opening a merge proposal. Review the status, comments, reviews, and merge checks before requesting the merge. For Bitbucket Cloud, strategy accepts merge_commit (or merge), squash, or fast_forward. Omit it to use the destination branch’s configured default; if that branch has no default, Genesis requests merge_commit. The approved proposal names the chosen strategy and whether Bitbucket will close the source branch. The merge is refused if the pull request is no longer open, its head changed since approval, or its configured branch does not allow the strategy. Bitbucket Server and Data Center merges are not supported. When Bitbucket queues a merge or has not finished it, Genesis does not retry it: the result remains uncertain until its task or merged state can be checked. For Bitbucket Cloud, get_pull_request_info always returns reviews (approvals and change requests). With include_ci=true, it also reads up to three pages each of comments and build statuses, plus Bitbucket’s merge checks; the maximum is eight API reads. It reports combined_status, ci_summary, merge_checks, mergeable, and merge_conflicts. mergeable is null when Bitbucket cannot evaluate the checks. Set include_ci=false to skip comments, build statuses, and merge checks while retaining reviews.
For repos registered as managed remote sources such as blueprints, apps, missions, and agents, Genesis hard-denies direct mutations of the managed base checkout. clone_repo, create_repo, delete_repo, set_repo_mode, configure_remote, pull, merge, reset, revert, and commit return success: false with error_code, managed_repo_guard, and next_steps. The error_code value is MANAGED_REMOTE_BASE_CHECKOUT_PROTECTED.
For managed artifacts, pass artifact_type and artifact_id on the file(...) call to select or create that artifact’s per-user WIP worktree. Use the same pair when opening review with git_action(action="create_pull_request", repo_id="...", title="...", body="...", artifact_type="...", artifact_id="..."). If a call is ambiguous, its response can list up to 10 candidate artifacts or branches; retry the same call with one listed type/id pair, or use a listed branch as branch_name. Candidate details are returned only when repository view access is confirmed; otherwise the response gives retry guidance without artifact ids, branch names, or paths. For managed agent definitions, set artifact_type="agent", artifact_id="&lt;agent_id&gt;", and file_path="agent.yaml". You can also use the type-specific workspace push tools (agent_management PUSH_TO_REPO, app_management, skill_management, etc.). Exception — Git-backed knowledge-base (documents) feeds: Genesis owns the managed checkout for KB content; git_action, file, and connection_api_action cannot write it. When a blocked mutation hits a documents/KB repo, the response includes managed_document_repo: true and next_steps that direct you to propose_kb_edit and open_kb_pull_request in Document Index Tools. Those tools accept supported KB files (.md, .yml, .yaml, .json, .txt, or .csv) under a first-level folder in documents_root; the PR tool reports its authoritative changed_files list. To refresh a managed source from origin, use git_action(action="sync_managed_source", repo_id="...", bot_id="..."). To retire it, call git_action(action="unregister_managed_source", repo_id="...") before git_action(action="delete_repo", repo_id="..."). To change the stored connection or remote URL, re-register the source from the dashboard’s Manage Sources modal on the relevant Skills, Flows, or Apps page instead of calling configure_remote. For a corrupted checkout or clean re-clone, use Reset Checkout in that same modal.
A managed artifact push is itself governed by Action Review, including when Genesis delivers the approved push through GitLab’s Commits API fallback after a raw Git push is rejected. A pending review means the branch was not pushed and no pull request was opened; wait for the person’s decision instead of retrying. A denied push remains unwritten. GitLab’s Commits API setting changes only delivery of that already-approved push, not whether the push requires review.
Managed checkouts with no git remote. A managed source’s on-disk checkout can exist without a configured git remote (has_remote=false on list_repos(details=true)). Genesis cannot verify freshness against origin or maintain a fresh mirror in that case, but the working tree remains readable and editable. Use file() to edit files on the default branch, then commit only those files with git_action(action="commit", repo_id="...", stage_paths=[...], commit_message="..."). stage_paths is required for these shared base checkouts and must contain exact repo-relative file paths, not directories or globs. A commit is refused if the checkout is detached or not on its resolvable default branch; branch switching and pull requests are unavailable for a source with no remote. Sync is refused while user changes remain, so commit those changes before syncing. For a local managed source, syncing with release_ref="latest" resolves to the default branch rather than a release tag. Default reads on the managed base checkout — file(action="read") with no branch_name, file(action="list"), file(action="fast_search"), and related git_action file reads — serve content from the local checkout and attach freshness_notice: “This managed repository has no git remote configured, so freshness could not be verified against the remote source. Content was read from the local checkout and may be stale.” Pass an explicit branch_name when origin-backed reads are available, or re-register the managed source with a remote URL and connection when you need verified freshness and remote pull requests.
Managed checkout exclusions (checkout_exclude). Operators can configure an ordered checkout_exclude pattern list on a managed source (via Config → Managed Sources or POST / PATCH /api/managed-sources) to prune paths from the managed base checkout with Git sparse checkout. This is independent of include / exclude, which govern which artifacts Genesis discovers and enables and retire previously synced skills, flows, or apps that no longer match on the next sync. After sync, pruned paths are not on disk, so git_action(action="list_files"), file(action="list"), and the Git Browser tree for that repo_id will not show them. To read a pruned path from the remote without changing the checkout policy, use git_action(action="show", ref="origin/&lt;branch&gt;", ...) after git_action(action="fetch"). Per-user managed worktrees used for WIP edits (skills, flows, apps, agents) remain full checkouts even when the base checkout is sparse. Clearing checkout_exclude to [] and syncing restores a full base checkout on the next successful sync.
On managed GitLab repos, git_action(action="commit_files_via_api") can land a prepared diff through the GitLab Commits API. When the action uses a stored GitLab connection, it runs under Action Review like other remote writes. A pending_review result means nothing was committed; a review card is posted in the current thread, and you should not call the action again while it waits. The approval covers the canonical project path, branch, commit message, exact file contents, and the branch base. If a file or the branch changes before approval, propose the action again with the current values. A reconciliation_required result may or may not have committed, so do not retry it.If the install has no saved GitLab connection and its GitLab credential comes only from the GITLAB_TOKEN (or GITLAB_PRIVATE_TOKEN) environment variable, a commit no rule could cover runs directly, as before; a rule on another git action (only merge request notes, say) does not count. One a rule could cover goes to that rule with this deployment’s GitLab credential, the same one gitlab_api_request uses there, for every GitLab request it makes, the default-branch lookup when no start_branch is given included: the rule allows it, holds it for a person, or denies it, and the review card says it runs with this deployment’s GitLab credential, not a person’s. No person’s credential is ever used for it, and it is never sent if the GitLab it was approved for moves, if a saved connection is added, or if the requester can no longer use git_action. With an environment token beside saved connections that the call does not name, a policy that would hold or deny the commit still refuses it. A project that GitLab cannot resolve is refused.

file

Parameters
Repository file operations cannot read or change the .git metadata directory, including when a symlink points into it. Directory copies and archives omit Git metadata. For file(action="unzip"), a destination inside .git is refused; archive entries aimed there are skipped and listed in refused_files.
Bulk writes validate the files payload before writing. For action="write_multiple", files is required, must be a non-empty array, and every entry must be an object. For action="write" when a non-empty files value requests a bulk write, the same array-of-objects validation applies. If files is a JSON string, it must contain valid JSON that decodes to an array; otherwise the request fails without writing any files. Invalid entries identify their zero-based index in the error.
For file(action="search_replace") and file(action="edit"), successful applied edits return a compact result by default: replacements_made or edits_applied, changed_line_count, and up to 20 changed_lines (with changed_lines_truncated: true when more lines changed). Genesis omits the large preview (and, for edit, the per-edit changes array) unless you pass return_verbose_edit_result=true or use dry_run=true to preview without writing.
If repo_id is omitted for action="write", file paths are saved under uploads/&lt;thread_id&gt;/... with a fallback to uploads/misc/.... Successful writes also echo the resolved file_path and thread_scope so follow-on tools can reference the actual saved location. For action="read_multiple", repo_id is required.

File-write placeholder guidance

File writes refuse content that is a clipped-history preview or a compressed argument/result placeholder rather than the original text. This applies to content, bulk file content, and text replacements. The response uses error_code="content_clipped_from_history" and confirms that nothing was written. If an earlier call already wrote the file, read it back instead; to change it, send the complete text. When the response includes an archive_ref, retrieve the original argument with manage_thread_memory(action="GET_COMPRESSED_PARAM_ARCHIVE", archive_ref=...). GenesisApps WRITE_FILE and WRITE_FILES apply the same guard.
Transferring a file that already exists. Never read a file and write the same bytes back. When the source already lives in a repository Genesis can reach, transfer it server-side with file(action="copy") or file(action="move") — byte-exact, including binaries (zip, image, parquet), with no content in the arguments and nothing to truncate:
For a single source, target_path is the new filename; for multiple sources or cross-repo copies, it is the destination directory. Add target_repo_id to copy or move into another repo. Inline content on action="write" is for text you are authoring — never for bytes you just read.
Binary bytes not already on disk. For content the bot generated or supplied inline (not an existing repo path), write base64 with is_base64=true so it is decoded rather than stored as literal ASCII:
Without is_base64=true, the base64 string is written as literal ASCII text and the resulting file is corrupt. If is_base64=true is passed with content that is not valid base64, the tool returns a structured error instead of writing a bad file. For multi-file writes, set is_base64 inside each files[] item rather than at the top level.On unpaged reads, return_base64=true returns a size-limited byte range by default (truncated=true with a continuation hint), not the full file. It does not bypass structured-file refusal on the text path — a clipped JSON/XML prefix will not parse. Page with start_byte/max_bytes or read the whole file before decoding.
file(action="read") supports partial and targeted reads with start_line, max_lines, start_byte, max_bytes, end_byte, tail_bytes, max_chars (alias for max_bytes), search_pattern, context_lines_before, context_lines_after, max_matches, return_line_numbers, encoding, force_text, return_base64, and include_sha256. start_line is 1-based; a negative value counts back from the end of the file (for example, start_line=-20 with max_lines=20 reads the last 20 lines). max_lines defaults to 100. For files above ~10 KB, use action="search" first, then read only the window you need. file(action="read_multiple") accepts the same per-entry windows in files (for example [{path, start_line, max_lines}]); identical path-and-window entries are deduplicated, but you can request both the head and tail of one file as separate entries. When the target is a managed GitHub repo base checkout, Genesis reads remote truth instead of the shared local clone when the checkout has a git remote. Pass branch_name to read that ref on origin; omit it to read the managed default branch. When the checkout has no git remote, Genesis reads the local tree instead and includes freshness_notice (see the managed no-remote note above). For other checkouts, when branch_name names a branch other than the checked-out one, Genesis fetches and reads origin/<branch>; if the fetch fails, it reads the last-fetched ref with a warning when one exists, or returns an error if there is no ref to read. If that local branch has commits that are not on origin, Genesis reads the local branch and says so. On the origin-backed remote-read path, start_line, max_lines, and return_base64 are supported, but search_pattern, context_lines_before, context_lines_after, max_matches, start_byte, end_byte, max_bytes, tail_bytes, max_chars, return_line_numbers, force_text, and encoding return an explicit error. Binary content on the remote-read path must use return_base64=true.
For repository file reads, listings, and searches, Genesis also says when it cannot prove that a clone is the caller’s own and matches its default branch. The response includes copy_note or copy_notes, explaining that the copy may contain commits or uncommitted changes not on that branch, or could not be compared. When part of the comparison is unreadable, the note still reports what is known: for example, a known commit count is preserved when working-tree status cannot be read, and an unreadable fetch record says the remote branch may be behind. Genesis keeps reading that checkout as it is; it never substitutes the remote’s files. To inspect the remote default branch instead, fetch it and use git_action(action="show", repo_id="...", ref="origin/<default-branch>", file_path="...") or git_action(action="ls_tree", repo_id="...", ref="origin/<default-branch>"). Those actions include remote_ref_note when an origin/<branch> result may be stale because the clone has no successful fetch on record or its latest fetch failed.
For large reads, check truncated, size_capped, and total_size before parsing content or assuming the full file was returned. max_bytes (or the older alias max_chars) caps how many bytes of content a read returns; the window still stops on a whole-line boundary once those bytes are spent and sets size_capped. Requests above the tool-output file-read budget (default 65,536 bytes / 64 KB) are clamped to it. Pass a value larger than the file size to read it whole. When an unpaged read would clip structured single-document files (.json, .geojson, .xml, .yaml, .yml, or extensionless files whose content starts like JSON or XML), Genesis refuses with success: false and omits content rather than returning unparseable partial JSON/XML/YAML. Detection uses the file extension when it discloses the type, and content sniffing when the extension does not. The error includes total_size, truncated: true, and a short content_preview; page with start_byte/max_bytes or start_line/max_lines, raise max_bytes to read the file whole, or use file(action="inspect_structured_data") for JSON/XML. Line-oriented .jsonl/.ndjson files can still return partial content.
Successful remote reads can also include branch_name, sha, _remote_read, and _remote_read_window when Genesis applies a line window client-side. When Genesis reads the local checkout because the managed source has no git remote, responses include freshness_notice and may set source to local_tree instead of origin metadata. When return_base64=true, the response includes encoding="base64" and, for unpaged reads that exceed the byte limit, truncated=true with a byte-range continuation. Clipped base64 payloads that look like JSON or XML may also include structured_partial_warning. When include_sha256=true, the response includes content_sha256 and content_size_bytes for the complete file (hashing reads the full file even when you also pass line or byte windows).
file(action="read") sizes its own result to fit the file-read inline budget (default 65,536 bytes / 64 KB, configurable via tools.output_governor.file_read_budget_bytes or GENESIS_TOOL_OUTPUT_FILE_READ_BUDGET) and always returns inline content — never a spill reference. When more remains, responses include truncated and/or size_capped; continue from the reported end_line with another windowed read. A single line longer than the budget is the exception: it returns cut mid-line with partial_line set, and only start_byte / max_bytes can reach the remainder. When git_action(action="read_file") or file(action="inspect_structured_data") still exceeds the governor cap, Genesis returns tool_output_capped, preview, truncation_info, full_output_ref, and agent_guidance instead of the full inline payload. When full_output_ref is not null, the full text is saved under truncated_tool_outputs/&lt;thread_id&gt;/... in the apps BotGit repo. Re-reading that spill path uses the default inline budget (not the relaxed file-read budget), so page it back with file(action="read", file_path=full_output_ref, repo_id="apps", start_byte=0, max_bytes=N), continuing from each response’s continuation.next_start_byte. Use the byte range rather than a line window: only the byte range returns the saved copy exactly as it was written — the whole-file and line-window paths read the file in text mode, so a \r\n in the spilled output comes back as \n.
A single-file file action (write, edit, search_replace, append, insert, patch, or delete) whose repo_id="apps" path names a registered GenesisApp workspace is routed to that app’s workspace, as if you had passed its app_id as repo_id. This applies only when the path identifies that app’s workspace and the call has no second target. Bulk, pattern, copy, and move forms are not rerouted; use the app id as repo_id for those operations or use apps_action.
To update a GenesisApp safely, prefer apps_action(action="WRITE_FILE", app_id="sales-dashboard", path="app.py", content="...") or apps_action(action="WRITE_FILES", ...). The generic file tool can use the app id as repo_id, for example file(action="write", repo_id="sales-dashboard", file_path="app.py", content="..."). This is also the recommended form for bulk operations. Blocked responses include error, next_steps, blocked_by: "microapp_apps_repo_mutation_guard", app_id, rel_path, and matched_param.

file(action="create_archive")

Create a ZIP archive from an entire repository or a repo-relative file or folder. Genesis writes the generated ZIP under .archives/ in the repository and returns archive metadata such as archive_path, download_link, file_count, total_size, archive_size, output_filename, and repo_id.
file(action="create_archive") excludes housekeeping paths by default: .archives/, Python caches (__pycache__, *.pyc, *.pyo, *.pyd), OS artifacts (.DS_Store, Thumbs.db), node_modules/, virtual environments (.venv/, venv/), .env and .env.*, and microapp runtime scratch directories (.microapp_home/, .microapp_state/, .microapp_venv/). Git metadata is always excluded; include_git=true returns an error. Clone or push the repository to share its history.

ocr

Extract text from scanned PDFs and image files in a Git repository with the ocr tool. Set filepath to a repository-relative file path and provide its repo_id. method defaults to "auto" and tries Databricks, Snowflake, Tesseract, then the OCR engine built into macOS or Windows; for image files it can then use the chat model’s vision. Use "on_device" to select the local OS engine directly (Windows needs an OCR language installed; Linux has no on-device engine), or "databricks" to select Databricks ai_parse_document directly. The on-device and vision routes accept HEIC/HEIF images, including photos from iPhone; method="vision" remains limited to image files. For a PDF attached to the current chat, use the uploads repository, pass the upload-relative path as filepath, and set method="databricks". Genesis reads the file from that thread’s upload folder and sends it to Databricks for parsing:
OCR failure responses may include provider_error_code when available. Snowflake OCR failures also identify the failed stage with failed_step: create_stage, put_file, or parse_document. Completed OCR responses include Route, which identifies the route that read the file and any provider that failed first, and Tell_User, which asks the agent to report that route in its answer. For Snowflake stage permissions, see Snowflake OCR stage access.

pdf_parser

Parse a PDF stored in a Git repo. source="repo" is the only supported mode; URLs and the deprecated bot_storage source are not supported. Parameters Text is returned in reading order: two-column pages are read column by column, and cells in bordered tables are separated by tabs. Inline output ends on a whole-page boundary at the reply size limit. The response includes pages (start, end, total, next_start_page, and truncated) and a Truncation_Note when the reply limit stopped the read. If truncated is true, continue with start_page=pages.next_start_page. If pages.page_cut is true, one page alone exceeded the limit; only its beginning is returned, so use save_to_git=true to save all extracted text into the repository. A start_page beyond the document returns an error naming the page count. Each page’s extracted text also includes a Form fields: section for filled form values and checkbox states; empty fields, buttons, and signatures are omitted. If the PDF has form widgets but Genesis cannot read its form values, the page says so. A page may also include Text that may be invisible on the page (white on nothing, or under 2 pt): followed by text runs that appear near-white without a darker backdrop or are smaller than 2 pt. Treat these as possible visibility issues to check against the page, not as a determination that the text is hidden or meaningful.
bot_id, thread_id, and user_id are injected from the current tool context. On managed remote repos, Genesis reads the PDF from the active WIP worktree when available; otherwise it parses the current remote file contents instead of the shared local clone.
When save_to_git=true on a managed remote repo, Genesis requires a WIP worktree and writes the extracted text there. If one is not selected, call file(action="read", repo_id="&lt;repo&gt;", file_path="&lt;path&gt;", artifact_type="&lt;type&gt;", artifact_id="&lt;id&gt;") to select or create it, then retry. The tool returns error_code="MANAGED_REMOTE_SAVE_REQUIRES_WIP" when a WIP worktree is required; if managed-artifact registry status cannot be read, it returns error_code="MANAGED_REMOTE_SAVE_STATUS_UNKNOWN" and recommends retrying when the registry is available or parsing read-only with save_to_git=false.

markdown_to_pdf

Convert a repo Markdown file into a PDF saved back into a Git repo. Genesis can render Mermaid diagrams and Plotly charts during conversion. Each render runs on the browser event loop rather than the server event loop and has a 120-second budget; a timed-out render is cancelled and the tool returns an error. Parameters
source_path can also carry the repo directly, such as uploads:thread-1/poem.md, when the source document lives outside the default bot_git repository.
Successful markdown_to_pdf responses include pdf_path, repo_id, git_url, download_link, and file_size. git_url is a root-relative Genesis link, resolving as /api/git/... in standalone and local deployments and /git/... in SPCS.
In a Databricks App deployment without Chromium, markdown_to_pdf returns a clear unavailable error before rendering starts. Save the document as Word (DOCX) or HTML instead; HTML keeps Mermaid and Plotly diagrams for rendering when opened in a browser.
In the Git browser and file preview, DOCX downloads now render fenced mermaid and plotly blocks as inline images in the generated Word document. Plotly DOCX exports also resolve data_source.query_id references before rendering so Word output stays aligned with markdown_to_pdf. If rendering is unavailable, Genesis inserts a short placeholder line instead of the raw diagram or chart source.

Bulk Pattern File Operations

For copy_files and file(action="copy"), set dry_run=true to inspect a read-only copy plan. When source files match, the response includes dry_run: true, would_copy_count, and up to 10 planned_files with source, target, and size; copied_count stays zero because no files are written. Managed-remote repositories are refused with error_code: "COPY_PREVIEW_MANAGED_REPOSITORY", including existing WIP worktrees, because resolving them can create or refresh a worktree. Use an ordinary local repository for a copy preview.
Directory references are auto-expanded for copy_files, move_files, and delete_files. When preserve_structure is true, glob patterns keep the nested path below the matched parent scope. Exact file paths use their parent directory as that scope, so source_patterns=["reports/monthly/summary.md"] writes archive/summary.md instead of archive/reports/monthly/summary.md.
copy_files applies symlink confinement on the source repo: matched entries whose real path resolves outside the source root are refused (not copied) and recorded in escaped_symlinks (up to 10 entries) with escaped_symlink_count in the result. Refused symlinks are not errors — they prevent external host content from being pulled into the destination.
git_action(action="copy_files") and git_action(action="move_files") stage every copied or moved path when dry_run is false and the target repo has a git index (move_files also stages source deletions). Responses include files_staged and staged_count; staged_count matches copied_count or the target-side moved_count, not the length of the preview arrays. copied_files and moved_files are display samples only (capped at 10 and 50 entries); use copied_count, moved_count, or get_status before commit to verify large operations.

Batch File Reads

file(action="read_multiple") accepts a recommended maximum of 20 files per call and a hard limit of 100. Each files[] entry can be a path string or a {path, start_line, max_lines} object with its own line window. Total returned content is capped at 200 KB; when that limit is reached, remaining files are reported in skipped, skipped_preview, and files_skipped, and the top-level response adds continuation_hint. Large files are automatically truncated to about 20 KB, except structured single-document files (.json, .geojson, .xml, .yaml, .yml, or extensionless files whose content starts like JSON or XML) that exceed the per-file limit — those entries return success: false with an error instead of partial content. Successful reads include per-file content and size; truncated entries are marked with truncated: true and can also include truncation_info, continuation, encoding, file_type, total_size, returned_size, returned_lines, total_lines, start_line, end_line, start_byte, end_byte, and freshness_notice when Genesis read from a managed checkout with no git remote. If any entry is truncated, the batch response adds a warning explaining how to continue from the correct byte or line offset, and the top-level response includes files_truncated with the count of truncated files. Use file(action="read") for binary or Excel files.
Very large list, find, and unzip responses are previewed instead of returned in full. files and extracted_files previews are trimmed to the first 50 paths, and download_links previews are trimmed to the first 20 links. Use fields such as files_preview, files_truncated, files_omitted_count, total_files, files_continuation_hint, note, and narrowing_hint to narrow list or find queries, or extracted_files_preview and download_links_preview to inspect the extracted directory.

reclaim_duplicate_repos

Administrators can review and quarantine duplicate local clones of the same remote. A copy is reclaimed only when the checks show that removing it will not lose local work or remove a copy that is still in use. Copies with uncommitted or untracked files, unpublished commits or stashes, active project or Blueprint references, linked worktrees, recent use, or an unreadable remote are left alone. Set thread_copies=true to work on a thread’s own isolated clones and editing branches created by prepare_edit instead. A user can reclaim their own copies; an administrator can review everyone’s. A copy stays in place while its thread is working or its work cannot be checked. On an owner’s dry run, copies containing uncommitted files, ignored files, unpublished commits, or stashes appear under reclaim_with_loss with the listed work and a loss_confirmation code. Explain the listed losses and get the owner’s explicit agreement before confirming with confirm=true and that code as confirm_loss; an administrator cannot use this confirmation to remove another person’s work. Work that changes after the dry run is kept. Reclaimed copies stay restorable in quarantine for 14 days; owners may restore their own thread copies, and administrators may restore any entry. For thread copies, a confirm must also pass repo_ids naming exactly the copies the user agreed to; a confirm without it moves nothing. Use one ID for a request such as deleting a single copy. The dry run can be narrowed with the same list and returns in_quarantine with restorable entries visible to the caller. Copies written through Genesis in the last two minutes are held; the dry run says when to try again, rather than waiting for the write in the current turn. The dry run moves and deletes nothing and changes no access settings, but it fetches each inspected copy from its remote to refresh and prune its remote- tracking refs. Confirmed copies move to quarantine for 14 days, then the scheduled purge deletes them. Restore an entry before it expires:
The scheduled cleanup runs every six hours and is enabled by default: jobs.thread_copy_cleanup.enabled defaults to true, and jobs.thread_copy_cleanup.idle_days defaults to 7. It quarantines only clean, fully pushed isolated clones unused for that many days. It also removes finished, idle editing branches after git_worktrees.idle_reap_seconds (default 86400, 24 hours): their work must be pushed or merged into the default branch, with no running turn, operation, or Mission/project using the branch. Uncommitted or unpushed work is listed and kept; ignored build output does not keep a branch. The list_repos cleanup hint describes the seven-day isolated-copy quarantine.

Use Cases

  1. Repository curation
    • List, read, or batch read repository files to review generated assets before publishing.
  2. Document updates
    • Write content changes to markdown or config files and commit with a clear message.
  3. One-call save
    • Save a local report into the repo and auto-attach it to the current task for review.
  4. Change review
    • Read files or trees from a branch, tag, or SHA, compare refs, share a diff for approval, then apply it and commit.
  5. Release preparation
    • Create a feature branch, make changes, and track history for a clean audit trail.
  6. PDF ingest
    • Parse a PDF and store extracted text alongside the original for indexing.
remove_file**and ** apply_diff**can delete or overwrite content. ** Verify targets and keep changes committed to reversible branches.

Workflow/How It Works

  1. Discover
    • list_files to scope the repo or get_status to see pending changes.
  2. Isolate
    • create_branch and switch_branch to work safely on a feature line.
  3. Edit
    • write_to_file for text edits or save_file for efficient binary and one-call save and attach.
  4. Review
    • show, diff, generate_diff, and get_history to validate changes before commit.
  5. Publish
    • For standard repos, commit with a descriptive message and confirm via get_status. For managed remote sources, keep the staged changes on the per-user WIP branch and open review with create_pull_request instead of commit.
For binary assets, save_file avoids loading file bytes into chat context and pairs well with auto-registration and attachment.

Integration Relevance

  • file_manager_tools to register, attach, download, and paginate file content once saved.
  • project_manager_tools to align commits and artifacts with tasks and milestones.
  • document_index_tools to index committed docs for search and Q&A.
  • artifact_manager_tools to reference generated outputs with durable links.
  • google_drive_tools when you also need to export or mirror key outputs.

Configuration Details

  • Use relative repository paths for file_path fields.
  • Follow branch naming conventions that match your workflow.
  • Write clear commit_message values for traceability.
  • When auto_register is true, provide correct auto_attach_entity_type and auto_attach_entity_id.
  • Keep binary files in appropriate directories to avoid repo bloat.

Limitations or Notes

  1. Repository initialization and permissions are required for all actions.
  2. Large binaries can slow clone and history operations.
  3. Concurrent index mutations from multiple agents are serialized server-side, but concurrent edits to the same file content can still cause merge conflicts that require manual resolution.
  4. Network connectivity may be required for remotes and external PDF URLs.
  5. Auto-registration depends on the availability of file_manager_tools.
  6. PDF parsing quality varies based on document structure.

Output

  • Repository cloning
    • Successful git_action(action="clone_repo") responses include repo_id and repo_path; repo_path is the checkout path for the newly cloned repository. Reusing a clone adds already_cloned: true; shared handouts also set read_only: true. Reused-clone responses include refreshed (fetched_now, recent, or failed), updated_at (last successful fetch in UTC), behind_by (the number of commits on the default branch not in the checkout, or null when unknown), commit (the checkout’s current commit), and freshness. A failed fetch may also include refresh_error. If every matching clone is busy, Genesis returns error_code="EXISTING_CLONE_IN_USE" and does not make another clone.
  • Pull-request information
    • git_action(action="get_pull_request_info") returns pull-request metadata. For GitHub, include_ci defaults to true and includes the authenticated head-commit CI feeds; set it to false when only metadata is needed. See GitHub Connector Tools — Output for the CI fields, completeness signals, and partial-read errors.
  • Bulk pattern file operations
    • git_action(action="copy_files") returns copied_count, skipped_count, error_count, escaped_symlink_count, total_size, message, and a copied_files preview (up to 10 entries). With dry_run=true, it instead reports would_copy_count, planned_files (up to 10 entries), and dry_run: true without writing files or staging changes. When staging succeeds, non-preview responses also include files_staged and staged_count equal to copied_count. git_action(action="move_files") returns moved_count, collision_count, move_errors, collisions, cleaned_directories, message, and a moved_files preview (up to 50 entries), plus files_staged and staged_count for target additions when staging succeeds.
  • File Operations
    • For capped git_action(action="read_file") and file(action="inspect_structured_data") results, follow the shared spill guidance in Code Executor Tools — Output, including what to do when the spill save fails.
    • Confirmations for create, modify, remove, single-file reads, and batch read results with per-file success or error details plus content and size for successful reads. Managed base-checkout reads from a checkout with no git remote include freshness_notice and may set source to local_tree. For file(action="search_replace") and file(action="edit"), applied edits return counts plus changed_line_count and a bounded changed_lines sample by default; pass return_verbose_edit_result=true (or dry_run=true for a no-write preview) to also receive the before/after preview, and for edit the per-edit changes array. For unpaged reads that would clip structured single-document files (.json, .geojson, .xml, .yaml, .yml, or extensionless files whose content starts like JSON or XML — detected by extension or content sniffing), Genesis returns success: false with error, total_size, truncated: true, and content_preview but omits content. max_bytes (alias max_chars) caps returned content in bytes. return_base64=true on unpaged reads returns a size-limited partial with truncated=true and a byte-range continuation; it does not bypass this refusal, and clipped JSON/XML payloads may include structured_partial_warning. file(action="read") always returns inline content sized to the file-read budget, with truncated and/or size_capped when more remains; a line longer than the budget can return partial_line and requires start_byte/max_bytes to continue. Batch reads can also surface per-file truncated, size_capped, partial_line, truncation_info, continuation, encoding, file_type, total_size, returned_size, returned_lines, total_lines, start_line, end_line, start_byte, end_byte, and freshness_notice, plus top-level warnings, files_truncated, files_skipped, skipped_preview, and continuation_hint when the response is cut short. git_action(action="read_file") and file(action="inspect_structured_data") can still return tool_output_capped, preview, truncation_info, full_output_ref, and agent_guidance; in that envelope, truncation_info includes bucket, bytes_in, bytes_out, budget_bytes, and spill_path.
    • file(action="search") returns at most max_results matching-line records (default 100, hard maximum 1000). total_matches is exhaustive only when total_matches_is_exact=true; if counting times out or partially fails, usable results are retained, total_matches_is_exact=false, and total_matches covers successfully counted portions. returned_matches reports the records included in the response. Repository-wide searches return count metadata only (returned_matches=0, results=null); pass file_path to return matching text. Matching lines, not individual occurrences within a line, are counted. Lowering max_results limits returned text but does not reduce the filesystem work required to count matches. Direct git_action(action="search") supports context_lines from 0 through 20; the public file wrapper uses 2 context lines.
    • Failed file(...) mutations return success: false with error, failed_operation, file_path (when applicable), and exception_type. The error string names the operation and target file (for example write_file on 'docs/query.sql' failed: RuntimeError: index corrupt) and includes the exception class and message. For OSError subclasses whose message omits the affected path, Genesis also appends (path: '...') so you can tell a failed write from failed git housekeeping such as index staging. Staging failures after a successful write say staging in git index failed instead of implying the write itself failed. Credentialed remote URLs embedded in error text are redacted as https://***@host/....
    • Successful file(...) mutations on remote-backed repos can proceed when a required pre-mutation fetch fails. Those responses include warnings (and optionally hints) with the fail-open notice, plus _auto_fetch_warning and _auto_fetch metadata. Genesis states each distinct error or hint once — the same git error is not repeated across warnings, _auto_fetch_warning, nested _auto_fetch fetch results, and details.raw_error.
  • Ref-scoped file reads
    • git_action(action="show") returns content, encoding, resolved_ref, branch_name, commit_sha, sha, size, truncated, and max_chars. Binary reads also include binary=true. When content is clipped, truncation_notice explains how to pass a larger max_chars.
  • Tree and Ref Diffs
    • git_action(action="ls_tree") returns entries, count, truncated, max_entries, path, recursive, resolved_ref, branch_name, and commit_sha. git_action(action="diff") returns either patch with max_chars and optional stats, or name_status_entries with count and max_entries, plus from_ref, to_ref, from_commit_sha, to_commit_sha, path, and truncated.
  • Diff and Apply
    • Unified diff output and application results.
  • Commit and Branch
    • Commit hash, affected files, and branch confirmations for standard repos. Successful commits can include auto_healed: true when Genesis rebuilt a corrupted local clone from remote during the commit preflight. When only unneeded loose objects are damaged (nothing refers to them), successful commits can also include integrity_warnings, damaged_object_paths, and integrity_hint with guidance to run quarantine_corrupt_objects. Corruption failures return error_code: GIT_REPOSITORY_CORRUPTED with validation, recovery_options, and optional auto_heal_attempted. When recovery_options reports damaged but unneeded loose objects, it can list warnings, unneeded_object_paths, and a quarantine_corrupt_objects option with data_loss_risk: "none". When a damaged object is still referred to, recovery_options can include needed_object_ids, needed_object_paths, staged_files_for_needed_objects, a warning or recommendation, and — when every needed object is staged from the working tree — a restore_object_from_working_tree option with data_loss_risk: "none".
    • git_action(action="commit", dry_run=True) returns a read-only preview envelope (dry_run: true, no commit_hash) with already_staged, would_stage, would_commit, changed_files, untracked_files, conflicted_files, remaining_conflicted_files, diff_summary, can_commit, preview_exact, optional staging_would_fail, rejected_stage_paths, unmatched_stage_paths, and an uncertainty object when transforms or unsupported entry types prevent an exact preview. Failures set success: false with error and may include error_code, unmatched_stage_paths, or rejected_stage_paths.
  • Repository integrity
    • git_action(action="quarantine_corrupt_objects") returns success, message, quarantined, quarantine_dir, and repository_valid_after on success. Failures return error with optional needed_object_ids, staged_files_for_needed_objects, fsck_output, skipped, and fsck_output_after.
  • Index lock recovery
    • git_action(action="force_unlock") returns success, message, and lock_file when index.lock is cleared (or was already absent). Failures return error, lock_file, and optional recovery_hint. When automatic retries still fail, commit and other index mutations can return lock_detected: true with recovery_action and recovery_hint instead of a generic error alone.
  • Remote sync
    • git_action(action="push") returns branch and refs_pushed on success. Bare push and explicit branch_name both set upstream tracking on the remote branch. Bitbucket Cloud uses git push with the saved connection credentials, preserving the local commit and history; it also passes the same code-scan preflight as other Git hosts. Without push_timeout_seconds, its push is bounded to five minutes.
    • git_action(action="pull") returns a success message that includes the merge/rebase strategy used.
    • When fetch or pull fails because the repository’s connection is unavailable to you, cannot sign in, or is refused by the host, Genesis can try up to three of your own usable connections configured for that host. A connection that reaches the repository is used for that call only; the repository keeps its configured connection. The response’s connection_fallback identifies the attempted and selected connections. Passing connection explicitly disables fallback. Fetches run automatically before reads or edits never fall back.
    • When the current branch cannot be resolved (detached HEAD) or Git reports no upstream tracking, push and pull return error_code="git_no_upstream_branch" with remediation.action="set_branch_name" — retry with branch_name='<branch>'.
    • git_action(action="fetch") returns changed refs in updates. Each update includes ref, branch, old_commit, new_commit, and flag, where flag is one of fast_forward, forced_update, new_head, new_tag, tag_update, rejected, error, or other. Refs already up to date are excluded from updates; no_op=true identifies a successful fetch with no changed refs, current_head_commits maps fetched refs to their current SHAs, and branches_updated counts only changed refs.
    • git_action(action="list_connections") reports usable_by_you, a status, and per-host health and git_access. A host is connected only after a fetch or pull reached it; health is unmeasured until then. org_access_restricted names GitHub organizations that block the OAuth app and includes what to ask an owner. list_remote_repos reports the same organization restriction instead of silently omitting the organization.
    • Managed-remote branch fetches for ref reads use the origin connection’s credentials, using the supplied connection when present or the connection resolved for that remote. When push, pull, fetch, clone, or other remote git operations fail, Genesis returns a normalized payload with success: false, error_code (for example git_operation_failed, git_timeout, git_network_error, git_no_upstream_branch, git_auth_failed, git_credentials_not_applied, git_authz_denied, or git_authz_scope_insufficient), credential-redacted error, and details containing operation, repo_id, remote_url, connection, connection_type, connection_name, exception_type, and errno_path when the underlying exception carries a filesystem path. git_credentials_not_applied means Git sent no credentials for the operation, rather than credentials being rejected; its remediation is to check that the remote has a connection (using list_remotes or configure_remote) or pass connection explicitly. details.raw_error is omitted when it would duplicate error (the usual case). Optional remediation includes action and message guidance (for example check_connection_credentials after an auth failure).
  • Managed source protection
    • Direct base-checkout mutations on managed remote sources return success: false with error_code, error, managed_repo_guard, next_steps, and registry_lookup_failed. When staged copy_files or delete_files operations target a managed source, next_step directs you to create_pull_request on the per-user WIP worktree instead of commit. When a blocked mutation (git_action mutating actions or file write/delete/copy/move actions) targets a repo that hosts a registered documents (Knowledge Base) artifact, the response also includes managed_document_repo: true and KB-specific next_steps (with a source_id_or_index hint) pointing to propose_kb_edit and open_kb_pull_request — not the generic WIP worktree flow. Blocked reads do not include KB steering. For managed document feeds, stage markdown with propose_kb_edit or /api/managed-sources/{source_id}/workspace/propose instead of direct index mutations or file(action="write").
  • History and Status
    • Commit lists with timestamps, authors, and messages, plus working tree status.
  • Repository Discovery
    • git_action(action="list_repos") returns visible repo ids. With details=True, each detail row includes mode, kind, has_git_dir, has_remote, scope, owner_user_id, owner_bot_id, and undeletable, plus credentials-redacted remote_url when present, clone_source when Genesis can infer the remote platform, and path when include_paths=True. kind is git_repository for entries that accept git actions and storage_workspace for storage-only entries. The detailed response also includes git_repositories, storage_workspaces, and git_repository_ids; these counts and ids cover the whole visible listing, not just the current page. mode is the repository’s effective mode, while has_git_dir reports the physical .git entry, so a reserved storage-only repository can have mode: "storage" and has_git_dir: true. When RBAC hides repos, the response can include hidden_by_access_count. Passing repo_id performs an exact or resolved existence check: a local id match returns exists: true; a remote org/name or URL resolves to the visible local clone and can return matched_by, resolved_from, and remote_url. No match returns error_code="REPO_REFERENCE_NOT_FOUND"; multiple matches return error_code="REPO_REFERENCE_AMBIGUOUS" with candidates. If detailed discovery finds unregistered blueprint repositories, unconfigured_repos and a count-aware unconfigured_next_step explain that the user must register them in the Blueprint dashboard; see Blueprint Library and Missions.
    • If detailed results include remote-backed clones, each row has remote_group; provenance includes kind and created_at. It includes created_by_user_id, created_by_bot_id, and created_thread_id only for the matching created_by_user_id or an administrator, so another viewer does not learn a private thread ID from the copy name. When multiple clones of one remote appear on the page, duplicate_of points each extra copy to the preferred clone and is null on that preferred row. duplicate_summary counts extra copies on the current page. The preferred clone is this thread’s isolated copy when present, otherwise the clone named like the remote, otherwise the most recently fetched.
    • When detailed results include multiple clones of one remote, each matching row has remote_group; recorded provenance appears in provenance, and duplicate_of points extra copies to the preferred clone (null on the preferred row). duplicate_summary counts extra copies in the current page. The preferred clone is this thread’s isolated copy when present, otherwise the clone named like the remote, otherwise the most recently fetched.
  • Repo reference resolution
    • Repo-scoped actions that resolve a remote reference attach resolved_repo_id, resolved_from, and matched_by to successful responses when the caller passed a remote org/name or URL instead of a local clone id. When multiple visible clones match the same remote, the response also includes selected_by and other_copies.
  • Blocked GenesisApp mutations
    • Bulk or unsupported file(...) mutations through repo_id="apps" that target a registered GenesisApp workspace return success: false with error, next_steps, blocked_by, app_id, rel_path, and matched_param. Supported single-file mutations are routed to the app workspace instead; see the guidance above.
  • Large Path and Archive Previews
    • file(action="list") and file(action="find") can return files_preview, files_truncated, files_omitted_count, total_files, files_continuation_hint, note, and narrowing_hint when many paths match. file(action="unzip") can similarly preview extracted_files and download_links with fields such as extracted_files_preview, extracted_files_truncated, extracted_files_omitted_count, total_extracted_files, extracted_files_continuation_hint, download_links_preview, download_links_truncated, download_links_omitted_count, total_download_links, and download_links_continuation_hint.
  • Auto-switch to default branch
    • On the first eligible content read per thread/session/repo key, file(...) and git_action(...) responses can include _auto_branch_switch. When Genesis switches the clone, the object has auto_switched: true, from_branch, to_branch, and message. When the switch is skipped, it has auto_switch_skipped: true, reason (for example dirty_working_directory or switch_failed), current_branch, default_branch, and message. A dirty_working_directory skip means modified, staged, conflicted, or user-owned untracked paths are present; Genesis internal untracked metadata (.genesis/, .genesis-sync.lock, .genesis-sync.lock.lock) does not count as dirty.
  • Zero-result repo search warning
    • git_action(action="search"), git_action(action="grep"), file(action="search"), and file(action="fast_search") can include a _branch_warning object when total_matches or count is 0 and the repo is on a non-default branch. The object includes current_branch, default_branch, and message, which directs you to switch to the default branch, run git_action(action="pull"), and retry the search.
  • Managed-remote search freshness
    • On managed remote repos, git_action(action="search") and git_action(action="grep") against the managed base checkout run against refreshed origin state instead of the shared local clone. Searches against a WIP worktree still use that worktree. When the managed checkout has no git remote, file(action="fast_search") searches the local checkout and includes freshness_notice instead of failing mirror preparation. file(action="list") and default managed file(action="read") follow the same local-tree fallback with freshness_notice.
  • PDF Parsing
    • Extracted text and metadata ready for indexing or analysis. When save_to_git=true, responses also include Saved_To_Git, Repo_ID, Git_Path, Total_Characters_Extracted, Content_Preview_Only, Context_Limit_Bypassed, Stats, Warnings, and a truncated Content preview.