Guide
Code search
File matches by query, global or scoped to an owner or a repository, on the platforms that have an endpoint for it.
Call
const result = await forge.code.search("defineNuxtConfig", {
owner: "nitrojs",
repo: "nitro",
perPage: 20,
});
for (const item of result.items) {
console.log(item.repository, item.path, item.url);
}
console.log(result.incomplete);
CodeSearchOptions is cursor, perPage and an optional owner and repo scope. A repo without an owner is a 400 before any request. The result is a SearchPageResult<CodeSearchItem> with repository, path and url per row.
Per platform
| Platform | Scope | Fine print |
|---|---|---|
| GitHub | global, owner, repository | a token raises the rate limit; incomplete is true on a timeout, a dropped row or past the cap of 1 000 results |
| GitLab | global, group (owner), project (repository) | every search call needs a token; global and group code search also need Premium or Ultimate with advanced or exact code search on |
| Gitea, Forgejo | none | explicit ForgesError with status 501 |
| GitHub API hosts without the endpoint | none | explicit ForgesError with status 501 |
On GitHub the scope is checked on the rows too, not just in the query. A row from outside the requested owner or repository is dropped and incomplete goes true, instead of a stray match from somewhere else quietly landing in your list.
In an agent
forges_code_search takes the same arguments. Like every read tool it falls back to anonymous access when there is no credential, which on GitLab means a clear message about the token rather than a bare 401.