Overview
Tool group
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. Usefile 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.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:
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.
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.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.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.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 omitsconnection, 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
Useshow, 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; setforce=True to use Git’s force-delete
behavior instead.
Azure DevOps Remote Workflows
Use the existing remote-repository and pull-request actions withplatform="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
Forcreate_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)
Setdraft=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.
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.
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 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="<agent_id>", 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/<branch>", ...) 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.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 For a single source,
file(action="copy") or
file(action="move") — byte-exact, including binaries (zip, image,
parquet), with no content in the arguments and nothing to truncate: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
Without
is_base64=true so it is decoded rather than stored as literal ASCII: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.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/<thread_id>/... 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.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="<repo>", file_path="<path>", artifact_type="<type>", artifact_id="<id>") 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.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:
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
- Repository curation
- List, read, or batch read repository files to review generated assets before publishing.
- Document updates
- Write content changes to markdown or config files and commit with a clear message.
- One-call save
- Save a local report into the repo and auto-attach it to the current task for review.
- Change review
- Read files or trees from a branch, tag, or SHA, compare refs, share a diff for approval, then apply it and commit.
- Release preparation
- Create a feature branch, make changes, and track history for a clean audit trail.
- PDF ingest
- Parse a PDF and store extracted text alongside the original for indexing.
Workflow/How It Works
- Discover
list_filesto scope the repo orget_statusto see pending changes.
- Isolate
create_branchandswitch_branchto work safely on a feature line.
- Edit
write_to_filefor text edits orsave_filefor efficient binary and one-call save and attach.
- Review
show,diff,generate_diff, andget_historyto validate changes before commit.
- Publish
- For standard repos,
commitwith a descriptive message and confirm viaget_status. For managed remote sources, keep the staged changes on the per-user WIP branch and open review withcreate_pull_requestinstead ofcommit.
- For standard repos,
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_pathfields. - Follow branch naming conventions that match your workflow.
- Write clear
commit_messagevalues for traceability. - When
auto_registeris true, provide correctauto_attach_entity_typeandauto_attach_entity_id. - Keep binary files in appropriate directories to avoid repo bloat.
Limitations or Notes
- Repository initialization and permissions are required for all actions.
- Large binaries can slow clone and history operations.
- 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.
- Network connectivity may be required for remotes and external PDF URLs.
- Auto-registration depends on the availability of
file_manager_tools. - PDF parsing quality varies based on document structure.
Output
- Repository cloning
- Successful
git_action(action="clone_repo")responses includerepo_idandrepo_path;repo_pathis the checkout path for the newly cloned repository. Reusing a clone addsalready_cloned: true; shared handouts also setread_only: true. Reused-clone responses includerefreshed(fetched_now,recent, orfailed),updated_at(last successful fetch in UTC),behind_by(the number of commits on the default branch not in the checkout, ornullwhen unknown),commit(the checkout’s current commit), andfreshness. A failed fetch may also includerefresh_error. If every matching clone is busy, Genesis returnserror_code="EXISTING_CLONE_IN_USE"and does not make another clone.
- Successful
- Pull-request information
git_action(action="get_pull_request_info")returns pull-request metadata. For GitHub,include_cidefaults totrueand includes the authenticated head-commit CI feeds; set it tofalsewhen 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")returnscopied_count,skipped_count,error_count,escaped_symlink_count,total_size,message, and acopied_filespreview (up to 10 entries). Withdry_run=true, it instead reportswould_copy_count,planned_files(up to 10 entries), anddry_run: truewithout writing files or staging changes. When staging succeeds, non-preview responses also includefiles_stagedandstaged_countequal tocopied_count.git_action(action="move_files")returnsmoved_count,collision_count,move_errors,collisions,cleaned_directories,message, and amoved_filespreview (up to 50 entries), plusfiles_stagedandstaged_countfor target additions when staging succeeds.
- File Operations
- For capped
git_action(action="read_file")andfile(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
contentandsizefor successful reads. Managed base-checkout reads from a checkout with no git remote includefreshness_noticeand may setsourcetolocal_tree. Forfile(action="search_replace")andfile(action="edit"), applied edits return counts pluschanged_line_countand a boundedchanged_linessample by default; passreturn_verbose_edit_result=true(ordry_run=truefor a no-write preview) to also receive the before/afterpreview, and foreditthe per-editchangesarray. 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 returnssuccess: falsewitherror,total_size,truncated: true, andcontent_previewbut omitscontent.max_bytes(aliasmax_chars) caps returned content in bytes.return_base64=trueon unpaged reads returns a size-limited partial withtruncated=trueand a byte-rangecontinuation; it does not bypass this refusal, and clipped JSON/XML payloads may includestructured_partial_warning.file(action="read")always returns inlinecontentsized to the file-read budget, withtruncatedand/orsize_cappedwhen more remains; a line longer than the budget can returnpartial_lineand requiresstart_byte/max_bytesto continue. Batch reads can also surface per-filetruncated,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, andfreshness_notice, plus top-levelwarnings,files_truncated,files_skipped,skipped_preview, andcontinuation_hintwhen the response is cut short.git_action(action="read_file")andfile(action="inspect_structured_data")can still returntool_output_capped,preview,truncation_info,full_output_ref, andagent_guidance; in that envelope,truncation_infoincludesbucket,bytes_in,bytes_out,budget_bytes, andspill_path. file(action="search")returns at mostmax_resultsmatching-line records (default100, hard maximum1000).total_matchesis exhaustive only whentotal_matches_is_exact=true; if counting times out or partially fails, usable results are retained,total_matches_is_exact=false, andtotal_matchescovers successfully counted portions.returned_matchesreports the records included in the response. Repository-wide searches return count metadata only (returned_matches=0,results=null); passfile_pathto return matching text. Matching lines, not individual occurrences within a line, are counted. Loweringmax_resultslimits returned text but does not reduce the filesystem work required to count matches. Directgit_action(action="search")supportscontext_linesfrom0through20; the publicfilewrapper uses2context lines.- Failed
file(...)mutations returnsuccess: falsewitherror,failed_operation,file_path(when applicable), andexception_type. Theerrorstring names the operation and target file (for examplewrite_file on 'docs/query.sql' failed: RuntimeError: index corrupt) and includes the exception class and message. ForOSErrorsubclasses 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 saystaging in git index failedinstead of implying the write itself failed. Credentialed remote URLs embedded in error text are redacted ashttps://***@host/.... - Successful
file(...)mutations on remote-backed repos can proceed when a required pre-mutation fetch fails. Those responses includewarnings(and optionallyhints) with the fail-open notice, plus_auto_fetch_warningand_auto_fetchmetadata. Genesis states each distinct error or hint once — the same git error is not repeated acrosswarnings,_auto_fetch_warning, nested_auto_fetchfetch results, anddetails.raw_error.
- For capped
- Ref-scoped file reads
git_action(action="show")returnscontent,encoding,resolved_ref,branch_name,commit_sha,sha,size,truncated, andmax_chars. Binary reads also includebinary=true. When content is clipped,truncation_noticeexplains how to pass a largermax_chars.
- Tree and Ref Diffs
git_action(action="ls_tree")returnsentries,count,truncated,max_entries,path,recursive,resolved_ref,branch_name, andcommit_sha.git_action(action="diff")returns eitherpatchwithmax_charsand optionalstats, orname_status_entrieswithcountandmax_entries, plusfrom_ref,to_ref,from_commit_sha,to_commit_sha,path, andtruncated.
- 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: truewhen 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 includeintegrity_warnings,damaged_object_paths, andintegrity_hintwith guidance to runquarantine_corrupt_objects. Corruption failures returnerror_code: GIT_REPOSITORY_CORRUPTEDwithvalidation,recovery_options, and optionalauto_heal_attempted. Whenrecovery_optionsreports damaged but unneeded loose objects, it can listwarnings,unneeded_object_paths, and aquarantine_corrupt_objectsoption withdata_loss_risk: "none". When a damaged object is still referred to,recovery_optionscan includeneeded_object_ids,needed_object_paths,staged_files_for_needed_objects, awarningorrecommendation, and — when every needed object is staged from the working tree — arestore_object_from_working_treeoption withdata_loss_risk: "none". git_action(action="commit", dry_run=True)returns a read-only preview envelope (dry_run: true, nocommit_hash) withalready_staged,would_stage,would_commit,changed_files,untracked_files,conflicted_files,remaining_conflicted_files,diff_summary,can_commit,preview_exact, optionalstaging_would_fail,rejected_stage_paths,unmatched_stage_paths, and anuncertaintyobject when transforms or unsupported entry types prevent an exact preview. Failures setsuccess: falsewitherrorand may includeerror_code,unmatched_stage_paths, orrejected_stage_paths.
- Commit hash, affected files, and branch confirmations for standard repos. Successful commits can include
- Repository integrity
git_action(action="quarantine_corrupt_objects")returnssuccess,message,quarantined,quarantine_dir, andrepository_valid_afteron success. Failures returnerrorwith optionalneeded_object_ids,staged_files_for_needed_objects,fsck_output,skipped, andfsck_output_after.
- Index lock recovery
git_action(action="force_unlock")returnssuccess,message, andlock_filewhenindex.lockis cleared (or was already absent). Failures returnerror,lock_file, and optionalrecovery_hint. When automatic retries still fail, commit and other index mutations can returnlock_detected: truewithrecovery_actionandrecovery_hintinstead of a generic error alone.
- Remote sync
git_action(action="push")returnsbranchandrefs_pushedon success. Bare push and explicitbranch_nameboth set upstream tracking on the remote branch. Bitbucket Cloud usesgit pushwith the saved connection credentials, preserving the local commit and history; it also passes the same code-scan preflight as other Git hosts. Withoutpush_timeout_seconds, its push is bounded to five minutes.git_action(action="pull")returns a success message that includes the merge/rebasestrategyused.- When
fetchorpullfails 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’sconnection_fallbackidentifies the attempted and selected connections. Passingconnectionexplicitly 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"withremediation.action="set_branch_name"— retry withbranch_name='<branch>'. git_action(action="fetch")returns changed refs inupdates. Each update includesref,branch,old_commit,new_commit, andflag, whereflagis one offast_forward,forced_update,new_head,new_tag,tag_update,rejected,error, orother. Refs already up to date are excluded fromupdates;no_op=trueidentifies a successful fetch with no changed refs,current_head_commitsmaps fetched refs to their current SHAs, andbranches_updatedcounts only changed refs.git_action(action="list_connections")reportsusable_by_you, a status, and per-hosthealthandgit_access. A host isconnectedonly after a fetch or pull reached it;healthis unmeasured until then.org_access_restrictednames GitHub organizations that block the OAuth app and includes what to ask an owner.list_remote_reposreports 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
connectionwhen present or the connection resolved for that remote. When push, pull, fetch, clone, or other remote git operations fail, Genesis returns a normalized payload withsuccess: false,error_code(for examplegit_operation_failed,git_timeout,git_network_error,git_no_upstream_branch,git_auth_failed,git_credentials_not_applied,git_authz_denied, orgit_authz_scope_insufficient), credential-redactederror, anddetailscontainingoperation,repo_id,remote_url,connection,connection_type,connection_name,exception_type, anderrno_pathwhen the underlying exception carries a filesystem path.git_credentials_not_appliedmeans Git sent no credentials for the operation, rather than credentials being rejected; its remediation is to check that the remote has a connection (usinglist_remotesorconfigure_remote) or passconnectionexplicitly.details.raw_erroris omitted when it would duplicateerror(the usual case). Optionalremediationincludesactionandmessageguidance (for examplecheck_connection_credentialsafter an auth failure).
- Managed source protection
- Direct base-checkout mutations on managed remote sources return
success: falsewitherror_code,error,managed_repo_guard,next_steps, andregistry_lookup_failed. When stagedcopy_filesordelete_filesoperations target a managed source,next_stepdirects you tocreate_pull_requeston the per-user WIP worktree instead ofcommit. When a blocked mutation (git_actionmutating actions orfilewrite/delete/copy/move actions) targets a repo that hosts a registered documents (Knowledge Base) artifact, the response also includesmanaged_document_repo: trueand KB-specificnext_steps(with asource_id_or_indexhint) pointing topropose_kb_editandopen_kb_pull_request— not the generic WIP worktree flow. Blocked reads do not include KB steering. For managed document feeds, stage markdown withpropose_kb_editor/api/managed-sources/{source_id}/workspace/proposeinstead of direct index mutations orfile(action="write").
- Direct base-checkout mutations on managed remote sources return
- 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. Withdetails=True, each detail row includesmode,kind,has_git_dir,has_remote,scope,owner_user_id,owner_bot_id, andundeletable, plus credentials-redactedremote_urlwhen present,clone_sourcewhen Genesis can infer the remote platform, andpathwheninclude_paths=True.kindisgit_repositoryfor entries that accept git actions andstorage_workspacefor storage-only entries. The detailed response also includesgit_repositories,storage_workspaces, andgit_repository_ids; these counts and ids cover the whole visible listing, not just the current page.modeis the repository’s effective mode, whilehas_git_dirreports the physical.gitentry, so a reserved storage-only repository can havemode: "storage"andhas_git_dir: true. When RBAC hides repos, the response can includehidden_by_access_count. Passingrepo_idperforms an exact or resolved existence check: a local id match returnsexists: true; a remote org/name or URL resolves to the visible local clone and can returnmatched_by,resolved_from, andremote_url. No match returnserror_code="REPO_REFERENCE_NOT_FOUND"; multiple matches returnerror_code="REPO_REFERENCE_AMBIGUOUS"withcandidates. If detailed discovery finds unregistered blueprint repositories,unconfigured_reposand a count-awareunconfigured_next_stepexplain 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;provenanceincludeskindandcreated_at. It includescreated_by_user_id,created_by_bot_id, andcreated_thread_idonly for the matchingcreated_by_user_idor 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_ofpoints each extra copy to the preferred clone and isnullon that preferred row.duplicate_summarycounts 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 inprovenance, andduplicate_ofpoints extra copies to the preferred clone (nullon the preferred row).duplicate_summarycounts 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, andmatched_byto 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 includesselected_byandother_copies.
- Repo-scoped actions that resolve a remote reference attach
- Blocked GenesisApp mutations
- Bulk or unsupported
file(...)mutations throughrepo_id="apps"that target a registered GenesisApp workspace returnsuccess: falsewitherror,next_steps,blocked_by,app_id,rel_path, andmatched_param. Supported single-file mutations are routed to the app workspace instead; see the guidance above.
- Bulk or unsupported
- Large Path and Archive Previews
file(action="list")andfile(action="find")can returnfiles_preview,files_truncated,files_omitted_count,total_files,files_continuation_hint,note, andnarrowing_hintwhen many paths match.file(action="unzip")can similarly previewextracted_filesanddownload_linkswith fields such asextracted_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, anddownload_links_continuation_hint.
- Auto-switch to default branch
- On the first eligible content read per thread/session/repo key,
file(...)andgit_action(...)responses can include_auto_branch_switch. When Genesis switches the clone, the object hasauto_switched: true,from_branch,to_branch, andmessage. When the switch is skipped, it hasauto_switch_skipped: true,reason(for exampledirty_working_directoryorswitch_failed),current_branch,default_branch, andmessage. Adirty_working_directoryskip 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.
- On the first eligible content read per thread/session/repo key,
- Zero-result repo search warning
git_action(action="search"),git_action(action="grep"),file(action="search"), andfile(action="fast_search")can include a_branch_warningobject whentotal_matchesorcountis0and the repo is on a non-default branch. The object includescurrent_branch,default_branch, andmessage, which directs you to switch to the default branch, rungit_action(action="pull"), and retry the search.
- Managed-remote search freshness
- On managed remote repos,
git_action(action="search")andgit_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 includesfreshness_noticeinstead of failing mirror preparation.file(action="list")and default managedfile(action="read")follow the same local-tree fallback withfreshness_notice.
- On managed remote repos,
- PDF Parsing
- Extracted text and metadata ready for indexing or analysis. When
save_to_git=true, responses also includeSaved_To_Git,Repo_ID,Git_Path,Total_Characters_Extracted,Content_Preview_Only,Context_Limit_Bypassed,Stats,Warnings, and a truncatedContentpreview.
- Extracted text and metadata ready for indexing or analysis. When

