Agent-friendly GitHub issue management for pi.
Sync issues, cache local context, and let agents manage GitHub Issues through safe structured tools.
---
IssueMe is a pi extension that gives LLM agents a repository-scoped GitHub Issues layer. It uses GitHub REST and GraphQL APIs, keeps bounded local JSON cache files for open issues, and exposes tools for syncing, triage, labels, milestones, comments, assignees, issue types, issue templates, Projects v2 boards and item ordering, native sub-issues, dependencies and related issues, issue history, linked-development inspection, confirmed issue deletion, and explicit bulk updates.
| IssueMe |
|
- **GitHub API native:** no GitHub CLI dependency and no shell execution for GitHub issue operations.
- **Repository scoped:** resolves the current `owner/repo` from trusted project context and validates GitHub request boundaries.
- **Agent tool suite:** registers forty-seven `issueme_*` tools for repository overview, issue, label, milestone, assignee, issue-type, issue-template, Projects v2 (discovery, items, maintenance, ordering), comment, sub-issue, dependency, related-issue, timeline, development-link, permanent-deletion, and bulk workflows.
- **Local issue cache:** writes open issues to `.pi/issues/-.json` (git-invisible via a directory-local `.gitignore`) so agents can inspect full bodies/comments without oversized tool results or a dirtied `git status`.
- **Safety-aware:** honors pi project trust, keeps tokens out of config/cache/tool output, limits closed-issue changes to labels, project-only board metadata, reopen, and confirmed deletion, bounds results, and requires explicit confirmation for destructive taxonomy and permanent issue-deletion operations.
- **Workflow friendly:** `/issueme` opens a non-secret configuration UI and `/issueme start [skill-path]` kicks off your project issue-management skill.
> **Status:** `0.1.0` is unreleased. Source, tests, this README, [`SECURITY.md`](SECURITY.md), and the files under [`docs/`](docs/) describe current implemented behavior.
> **Security:** pi packages run with your full system permissions. IssueMe reads GitHub tokens from trusted project or process environment, calls GitHub APIs for the current repository, and writes non-secret config plus local issue-cache files. It is not an OS sandbox. Read [`SECURITY.md`](SECURITY.md).
## Table of Contents
- [Quick Start](#quick-start)
- [Visual Workflow Guide](#visual-workflow-guide)
- [Installation](#installation)
- [Daily Usage](#daily-usage)
- [Commands](#commands)
- [Agent Tools](#agent-tools)
- [Configuration and Authentication](#configuration-and-authentication)
- [Safety Model](#safety-model)
- [Troubleshooting](#troubleshooting)
- [Update and Uninstall](#update-and-uninstall)
- [Development](#development)
- [Publishing](#publishing)
- [More Documentation](#more-documentation)
- [License](#license)
---
## Quick Start
```bash
pi install npm:@senad-d/issueme
cd /path/to/your/github/repo
```
Create a local `.env` from the example and provide a token with repository issue access:
```bash
cp .env.example .env
$EDITOR .env
```
`.env.example` documents the supported variables (`GH_TOKEN` or `GITHUB_TOKEN`, plus optional `GITHUB_REPOSITORY`) with safe placeholders.
Start pi and open IssueMe:
```bash
pi
```
```text
/issueme
```
Review non-secret settings, then get a read-only repository overview:
```text
Use issueme_get_overview to summarize issues, labels, milestones, assignees, and projects.
```
Drill into selected issues with the existing tools. Use `issueme_sync_issues` only when you need local issue/cache files.
Recommended workflow kickoff:
```text
/issueme start .pi/skills/github-issues/SKILL.md
```
If the npm package is unavailable before a public release, use the source checkout workflow below. See [`docs/configuration.md`](docs/configuration.md) for token/config details and [`docs/usage.md`](docs/usage.md) for workflow examples.
---
## Visual Workflow Guide
See [how IssueMe works and which workflows it supports](docs/workflows.md): seven diagrams covering architecture, the full 47-tool workflow map, daily issue management, native relationships, Projects v2, explicit bulk changes, and safe recovery.
[](docs/workflows.md)
Editable draw.io sources and zoomable SVGs are in [`docs/diagrams/`](docs/diagrams/README.md).
---
## Installation
| Scope | Command | Notes |
| --- | --- | --- |
| Global | `pi install npm:@senad-d/issueme` | Loads in every trusted pi project. |
| Project-local | `pi install npm:@senad-d/issueme -l` | Writes to `.pi/settings.json` in the current project. |
| One run | `pi -e npm:@senad-d/issueme` | Try without changing settings. |
| Git | `pi install git:github.com/senad-d/IssueMe@` | Pin a tag or commit. |
| Local checkout | `pi --no-extensions -e .` | Develop or test this repository. |
Requirements:
- pi with Node.js 22.19.0 or newer.
- A trusted project checkout.
- `GH_TOKEN` or `GITHUB_TOKEN` with repository issue access. Projects v2, native sub-issues, and linked-development inspection require the matching GitHub permissions/features; see [GitHub token types](#github-token-types) for which token type reaches which boards.
Source checkout:
```bash
git clone https://github.com/senad-d/IssueMe.git
cd IssueMe
npm ci
npm run validate
pi --no-extensions -e .
```
Use a checkout globally while developing:
```bash
pi install /absolute/path/to/IssueMe
```
---
## Daily Usage
Inside a trusted GitHub repository, run one of these in pi:
```text
/issueme
/issueme info
/issueme start .pi/skills/github-issues/SKILL.md
/issueme start
```
Recommended first run:
1. Add a GitHub token through trusted project or process environment.
2. Start pi from the repository checkout and trust the project if prompted.
3. Run `/issueme info` to confirm repository, token, config, and cache status without exposing secrets.
4. Run `/issueme` to review config such as issue directory, defaults, creator scope, and default skill path.
5. Ask the agent to call `issueme_get_overview` for initial planning; sync only when local issue files are needed.
6. Start your project workflow with `/issueme start [skill-path]`.
IssueMe provides tools; your project `SKILL.md` should describe your team's issue process. See [`docs/usage.md`](docs/usage.md) for a starter skill and prompt examples.
---
## Commands
| Command | Description |
| --- | --- |
| `/issueme` | Open the non-secret configuration UI in TUI mode; non-TUI modes show safe config/status output. |
| `/issueme info` | Show help, runtime status, registered tool names, cache counts, and troubleshooting hints without secrets. |
| `/issueme help`, `/issueme --help`, `/issueme -h` | Aliases for `/issueme info`. |
| `/issueme start [skill-path]` | Ask the agent to load a readable project-local issue workflow skill, or the configured `defaultSkillPath` when omitted. |
---
## Agent Tools
IssueMe registers forty-seven `issueme_*` tools. The most common flow is:
1. Orient: `issueme_get_overview` returns bounded summaries in one call, with no cache writes and at most five GitHub requests. Inspect section status; returned rows are not repository totals.
2. Drill down: `issueme_list_issues`, `issueme_get_issue`, taxonomy/people discovery, `issueme_list_issue_types`, `issueme_list_issue_templates`, `issueme_get_project_fields`, `issueme_list_project_items`, `issueme_list_issue_comments`, `issueme_list_sub_issues`, `issueme_list_issue_dependencies`, `issueme_list_related_issues`, `issueme_list_issue_timeline`, and `issueme_list_issue_development_links`. When a result is truncated, pass `details.continuation.nextToken` as `after` with the same filters to read the next page. Sync only when local cache files are needed.
3. Mutate explicitly: create/update/comment/assign/label/reopen/close issues, permanently delete one confirmed mistaken issue, manage label/milestone taxonomy, add/update/clear/archive/move/remove Projects v2 items, manage native sub-issues, blocked-by dependencies, and related issues, or bulk-update a confirmed list of issue numbers.
Use the detailed references when building agent workflows:
- [`docs/tool-reference.md`](docs/tool-reference.md) for the full tool catalog and examples.
- [`docs/public-contracts.md`](docs/public-contracts.md) for read/write behavior, execution modes, and result semantics.
- [`docs/usage.md`](docs/usage.md) for skill-guided workflow prompts.
---
## Configuration and Authentication
Project config is non-secret and stored at:
```text
.pi/agent/issueme.json
```
Supported settings include `issueDirectory`, `allowedIssueCreator`, `defaultLabels`, `defaultAssignees`, and `defaultSkillPath`. The optional `allowedIssueCreator` setting is an IssueMe processing scope only; it limits what IssueMe lists, syncs, reads, mutates, and caches, but it does not change GitHub repository permissions.
Token precedence:
1. trusted project `GH_TOKEN`;
2. trusted project `GITHUB_TOKEN`;
3. process `GH_TOKEN`;
4. process `GITHUB_TOKEN`.
Tokens are read but never written to config, cache files, tool output, or logs. Full configuration, trust, local cache, and request-boundary details are in [`docs/configuration.md`](docs/configuration.md).
### GitHub token types
IssueMe accepts either kind of personal access token and behaves the same with both. The difference is what GitHub lets the token reach.
| Token type | Grant | Covers | Cannot reach |
| --- | --- | --- | --- |
| Fine-grained personal access token | Repository permissions: Issues read and write, Metadata read, Contents read (issue template discovery). For organization boards add the organization permission Projects. | Every issue, comment, label, milestone, assignee, sub-issue, dependency, related-issue, timeline, development-link, issue-type, deletion, and bulk tool. Projects v2 boards owned by an organization. | Projects v2 boards owned by a user account. GitHub documents this as a limitation of fine-grained tokens, and no permission exists to grant it. |
| Classic personal access token | Scopes `repo` and `project` (`read:project` is enough for read-only board discovery). | Everything above plus user-owned Projects v2 boards. | Nothing, but `repo` grants access to every repository the account can reach, so prefer the fine-grained token unless you need a user-owned board. |
How the limitation shows up: with a fine-grained token the Projects v2 tools (`issueme_list_projects`, `issueme_get_project_fields`, `issueme_add_issue_to_project`, `issueme_update_project_item`, `issueme_list_project_items`, `issueme_get_project_item`, `issueme_remove_issue_from_project`, `issueme_clear_project_item_field`, `issueme_archive_project_item`, `issueme_move_project_item`) fail cleanly with `github_projects_v2_forbidden` ("Resource not accessible by personal access token"), and `issueme_get_overview` reports its projects section as unavailable while every other section still works. Nothing else degrades.
Independent of token type:
- `issueme_delete_issue` needs repository administrator permission.
- Native issue types persist only with push access; without it GitHub drops the type silently and IssueMe reports `partial_success`.
- Organization issue types need `read:org` on a classic token or the organization permission on a fine-grained token; user-owned repositories report `issue_types_unavailable`.
- `/issueme info` reports whether a token is present and where it came from, never its value.
Both token types were verified live against this repository on 2026-10-10; see [`docs/live-github-verification.md`](docs/live-github-verification.md).
---
## Safety Model
- IssueMe honors project-local config, tokens, Git metadata, skills, and cache files only when pi reports the project as trusted.
- Closed issues remain protected from content mutations; `issueme_label_issue` (and bulk `add_labels`/`remove_labels`) may change their labels, project-only board metadata tools (`issueme_update_project_item`, `issueme_clear_project_item_field`, `issueme_remove_issue_from_project`, `issueme_archive_project_item`) may change their board values or membership, and explicit `issueme_reopen_issue` (and bulk `reopen`) and confirmed `issueme_delete_issue` provide the other documented exceptions. Adding a closed issue to a board is still refused.
- `issueme_delete_issue` permanently deletes only one exact issue after explicit intent, an irreversibility warning, and `confirmDelete: true`; it accepts open or closed issues, refuses pull requests, and requires GitHub repository administrator permission.
- Repository label, milestone, and issue deletion require explicit actions and confirmation flags.
- Bulk updates accept only explicit issue number lists, never unconstrained search targets.
- Native sub-issues use GitHub GraphQL; IssueMe does not silently create body-only parent/dependency/blocker fallbacks.
- Tool results are bounded and include `details.result`/status metadata; agents should check both pi tool errors and IssueMe result details.
- IssueMe starts no webhooks, listeners, background servers, timers, file watchers, telemetry, or GitHub CLI processes.
### Issue dependencies and blockers
GitHub documents native issue dependency endpoints (`blocked_by` and `blocking`) in its REST API, and IssueMe implements them as `issueme_list_issue_dependencies`, `issueme_add_issue_dependency`, and `issueme_remove_issue_dependency`. Both ends of an edge must be open issues in the current repository and creator scope, the blocking issue is identified by its GitHub database id, self-dependencies are refused, already-present or already-absent edges are no-ops, and GitHub cycle/validation refusals come back as structured `result: error` results. Dependencies are prerequisites, distinct from sub-issues (decomposition) and related issues; IssueMe does not create body-only `blocked by`, `depends on`, or `tracked by` references as a silent fallback. [`docs/github-api-compatibility.md`](docs/github-api-compatibility.md) records that this support is documentation-verified and mocked, not live-verified.
Read [`SECURITY.md`](SECURITY.md) before installing in sensitive environments.
---
## Troubleshooting
| Problem | Try |
| --- | --- |
| `/issueme` refuses config editing | Trust the project first; project-local state is ignored until pi reports trust. |
| Token is missing | Set `GH_TOKEN` or `GITHUB_TOKEN` in trusted project or process environment. |
| Repository cannot be resolved | Set `GITHUB_REPOSITORY=owner/repo` or start pi from a trusted GitHub checkout. |
| Local issue files look stale | Run `issueme_sync_issues`, or `issueme_get_issue` with `refresh: true` for one known issue. |
| Expected issue is missing or refused | Check `/issueme info` for **Allowed issue creator** and update it in `/issueme` if needed. |
| Unknown label, milestone, assignee, project, or field | Use the matching read-only discovery tool before mutating. |
| Mutation is refused | Confirm the issue is open (unless explicitly reopening or deleting), in creator scope, and the target IDs/labels/users exist. Permanent deletion also requires `confirmDelete: true` and repository administrator permission. |
| Bulk update stopped | Inspect `details.bulkResults`, sync if cache state is uncertain, then retry only remaining explicit issue numbers. |
More troubleshooting notes live in [`docs/configuration.md`](docs/configuration.md), [`docs/tool-reference.md`](docs/tool-reference.md), and [`SECURITY.md`](SECURITY.md).
---
## Update and Uninstall
```bash
pi update --extensions
pi update npm:@senad-d/issueme
pi remove npm:@senad-d/issueme
pi remove npm:@senad-d/issueme -l
```
Removing the package does not automatically delete `.pi/agent/issueme.json` or local issue cache files. Review them before deleting manually.
---
## Development
```bash
npm ci
npm run validate
```
Useful checks:
```bash
npm run typecheck
npm run format:check
npm run test
npm run smoke:discover
npm run smoke:packaged
npm run smoke:handlers
npm run smoke:pi-lifecycle
npm run check:pack
pi --no-extensions -e .
```
Development, diagnostics, smoke-test, and live-verification notes are in [`docs/development.md`](docs/development.md).
---
## Publishing
IssueMe publishes to npm as `@senad-d/issueme`. Run from a clean working tree after updating `CHANGELOG.md`.
```bash
npm login
npm whoami
node scripts/publish-npm.mjs
```
The publish script validates, versions, tags, publishes with `npm publish --access public`, and offers to push the release commit and tag.
---
## More Documentation
- [`docs/workflows.md`](docs/workflows.md) - visual guide to architecture, supported workflows, and safe recovery; editable diagram sources included.
- [`docs/usage.md`](docs/usage.md) - daily workflows, starter `SKILL.md`, and prompt examples.
- [`docs/configuration.md`](docs/configuration.md) - config schema, auth, trust policy, local cache files, and GitHub request policy.
- [`docs/tool-reference.md`](docs/tool-reference.md) - complete tool catalog, result semantics, examples, and limitations.
- [`docs/development.md`](docs/development.md) - diagnostics, validation, smoke tests, and release workflow.
- [`docs/public-contracts.md`](docs/public-contracts.md) - public command/tool contract matrix.
- [`docs/github-api-compatibility.md`](docs/github-api-compatibility.md) - pinned REST version, documented versus tested GitHub capabilities, and open unknowns.
- [`docs/STRUCTURE.md`](docs/STRUCTURE.md) - source layout and architecture boundaries.
- [`docs/live-github-verification.md`](docs/live-github-verification.md) - opt-in live GitHub verification plan.
- [`docs/pi-lifecycle-verification.md`](docs/pi-lifecycle-verification.md) - manual pi lifecycle checks.
- [`SECURITY.md`](SECURITY.md) - security policy and threat model.
- [`CONTRIBUTING.md`](CONTRIBUTING.md) - contribution guidelines.
- [`CHANGELOG.md`](CHANGELOG.md) - release history.
---
## License
MIT