cluesmith Forge Concept Commands
Forge concept commands decouple codev from direct gh CLI calls. Each GitHub operation is routed through a configurable external command.
Concepts
| Concept | Env Vars | Description |
|---|---|---|
issue-view |
CODEV_ISSUE_ID |
Fetch issue details (JSON) |
pr-list |
— | List open PRs (JSON array) |
issue-list |
— | List issues (JSON array) |
issue-comment |
CODEV_ISSUE_ID, CODEV_COMMENT_BODY |
Post a comment on an issue |
pr-exists |
CODEV_BRANCH_NAME |
Check if a PR exists for a branch |
recently-closed |
CODEV_SINCE_DATE (optional) |
List recently closed issues |
recently-merged |
CODEV_SINCE_DATE (optional) |
List recently merged PRs |
user-identity |
— | Get current user's handle (plain text) |
team-activity |
CODEV_GRAPHQL_QUERY |
Run a batched GraphQL query |
on-it-timestamps |
CODEV_ISSUE_NUMBERS, CODEV_GRAPHQL_QUERY, CODEV_REPO_OWNER, CODEV_REPO_NAME |
Get "on it" comment timestamps |
pr-create |
CODEV_PR_TITLE, CODEV_PR_BODY, CODEV_PR_BASE (optional), CODEV_PR_HEAD (optional), CODEV_PR_REPO (optional), CODEV_PR_DRAFT (optional) |
Open a PR; prints {"number", "url"} |
pr-merge |
CODEV_PR_NUMBER |
Merge a PR |
pr-search |
CODEV_SEARCH_QUERY |
Search PRs (JSON array) |
pr-view |
CODEV_PR_NUMBER, CODEV_INCLUDE_COMMENTS (optional) |
View PR details (JSON or text) |
pr-diff |
CODEV_PR_NUMBER, CODEV_DIFF_NAME_ONLY (optional) |
Get PR diff |
auth-status |
— | Check forge authentication status |
Configuration
In .codev/config.json:
{
"forge": {
"provider": "gitlab",
"issue-comment": "my-custom-script $CODEV_ISSUE_ID"
}
}
Resolution order
- Manual concept override in
forgesection - Provider preset (if
provideris set) - Default (GitHub via
ghCLI)
Providers
Built-in presets: github (default), gitlab (via glab), gitea (via tea).
Note: Non-GitHub presets are best-effort. Output schemas may differ from GitHub's JSON contracts. Non-conforming JSON returns null — consumers handle this gracefully. Override individual concepts if a preset doesn't match your CLI version.
CODEV_REPO is overloaded. For repo-archive it is an input: the owner/repo to download. For the Gitea preset's read concepts (pr-view, pr-list, pr-exists, issue-view, recently-merged) it is an override — tea api needs an explicit owner/repo in the endpoint path, which those scripts otherwise derive from the origin remote. Set it per invocation, not in your environment: exported globally it retargets every Gitea read at that repo.
Disabling concepts
Set a concept to null to disable it:
{
"forge": {
"team-activity": null
}
}
Validation
Run codev doctor to see forge concept status, provider, and validation results.
Code
- Dispatcher:
packages/codev/src/lib/forge.ts - Contracts:
packages/codev/src/lib/forge-contracts.ts - Spec:
codev/specs/589-non-github-repository-support.md