feat: repo_tree tool (single-call directory tree) #14

New Issue

mathias · 2026-05-14T08:51:57Z

mathias commented

2026-05-14 08:51:57 +00:00

Summary

Add a repo_tree tool that returns the full directory tree of a repo (up to configurable depth) in a single call, instead of requiring repeated dir_list calls per directory.

Gitea API

GET /api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true

Tool spec

tool: repo_tree
params:
  owner:     string
  name:      string
  ref:       string?  // branch/tag/SHA, defaults to default branch
  max_depth: int?     // default: 3, max: 5
  path:      string?  // subtree root, defaults to repo root

Returns

Flat list of {path, type (file|dir), size, sha} entries, filtered to max_depth.

Required token permission

read:repository scope — same as existing tools, no new permissions needed.

Risk classification

LOW — read-only.

Motivation

During repo scouting (2026-05-14 session), exploring 6 repos required ~12 separate dir_list calls to understand structure. A single repo_tree call would have replaced all of them. Critical for efficient agent-driven repo exploration.

Implementation notes

Use Gitea's recursive tree API — don't implement recursion manually
Cap at max_depth to avoid huge responses on deep repos
Filter out .git internals
Consider size limit: truncate if > 200 entries, return truncation warning

## Summary Add a `repo_tree` tool that returns the full directory tree of a repo (up to configurable depth) in a single call, instead of requiring repeated `dir_list` calls per directory. ## Gitea API `GET /api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true` ## Tool spec ``` tool: repo_tree params: owner: string name: string ref: string? // branch/tag/SHA, defaults to default branch max_depth: int? // default: 3, max: 5 path: string? // subtree root, defaults to repo root ``` ## Returns Flat list of `{path, type (file|dir), size, sha}` entries, filtered to max_depth. ## Required token permission `read:repository` scope — same as existing tools, no new permissions needed. ## Risk classification **LOW** — read-only. ## Motivation During repo scouting (2026-05-14 session), exploring 6 repos required ~12 separate `dir_list` calls to understand structure. A single `repo_tree` call would have replaced all of them. Critical for efficient agent-driven repo exploration. ## Implementation notes - Use Gitea's recursive tree API — don't implement recursion manually - Cap at max_depth to avoid huge responses on deep repos - Filter out `.git` internals - Consider size limit: truncate if > 200 entries, return truncation warning

mathias referenced this issue from a commit

2026-05-15 08:24:19 +00:00

feat(tools): repo_tree, repo_topics_update, file_read dir fix (#14, #15, #18)

mathias referenced this issue

2026-05-15 08:24:28 +00:00

feat(tools): repo_tree, repo_topics_update, file_read dir fix (#14, #15, #18) #22

mathias referenced this issue from a commit

2026-05-15 08:24:36 +00:00

Merge pull request 'feat(tools): repo_tree, repo_topics_update, file_read dir fix (#14, #15, #18)' (#22) from feat/repo-ux into main

mathias commented

2026-05-18 06:12:37 +00:00

Shipped in v0.2.3. Closing during cleanup pass.