git-intent-picker (gip)

English | 日本語

A CLI tool that extracts "marker comments" embedded in your source code and converts them into Issues.

In modern AI-driven development (e.g., using AI agents for automated coding), this tool acts as an Intent Sidecar. It helps separate pure AI-generated code from human-crafted design intent, keeping your commit history clean and meaningful.

Currently, it extracts marker comments written in Python and semi-automatically converts them into GitHub or Gitea Issues.

Note

This README was also primarily generated by an AI agent.

This tool was born out of my initiatives in AI-assisted development.

When you delegate coding to AI agents, they often arbitrarily delete intentionally placed comments. I tried several workarounds for this behavior but couldn't find an effective solution. This led to a shift in my perspective: I realized that the very existential purpose of source code is changing due to AI agents, and I am now in a reality where I have lost nearly half of my control over it.

Rather than trying to fight this probabilistic behavior, I decided to acknowledge the AI's domain and find a way to coexist. I realized the developer's "intent" needed to be relocated outside the code. I chose GitHub Issues as the most straightforward approach—it solidifies the intent as a snapshot in Git history while providing excellent traceability and room for future expansion.

✨ Features

• Safe & Read-Only: Makes zero destructive changes (no automatic git restore or file deletion). You maintain full control over when to commit the cleanup.
• 1 Intent = 1 Issue: Automatically creates a dedicated Issue for each extracted marker comment block.
• Clean Text Output: Strips Python comment symbols (#) and unnecessary indentation, recording the Issue in clean, plain text.
• Perfect HEAD Commit Linking: Analyzes the latest commit (HEAD) to stamp a permanent, line-accurate link (e.g., #L12-L15) directly in the Issue body.
• Smart Title Generation: Automatically generates the Issue title by parsing the first line of your marker comment.
• Multi-Platform Support: Adopts an Adapter pattern that allows dynamically switching the Issue destination between GitHub and Gitea.

📦 Prerequisites

This tool requires the following:

• Python 3.x
• Git
• GitHub CLI (gh) — Used as a fallback when using GitHub and no API token is set.
• [IMPORTANT] Repository Label Configuration: When specifying a label via the GIP_LABEL environment variable, the behavior depends on the platform's specifications, so please create a label with the corresponding name on the repository in advance.

🚀 Installation

For macOS and Linux, we recommend installing via our custom Homebrew Tap. Dependencies (gh and python3) will be resolved automatically.

brew install gumi278/tap/gip

Once installed, the gip command is available globally (Note: gh auth login is required prior to use).

Getting the Latest Version (Manual Installation)

If you prefer the bleeding-edge version or don't use Homebrew, you can clone the repository and run it locally. The entry point is src/gip/main.py.

git clone https://github.com/gumi278/git-intent-picker.git

# Example usage:
# python3 git-intent-picker/src/gip/main.py

💻 Usage

1. Writing Marker Comments

In your working tree, write a comment starting with the prefix # @yourname in a .py file and commit it.

• The line must start with a # (leading indentation is fine).
• We highly recommend matching the "name" in the prefix with your git config user.name (this saves you from passing it as a CLI argument).
• Follow the name immediately with a space, a colon (:), or a newline to prevent false positives.

    def calculate_total():
        # @alice: Regarding Dependency Injection
        # We designed this to ensure testability by using DI
        # instead of directly calling the external API here.
        pass

1.1 Common Pitfalls

• It only reacts to the latest commit (HEAD)

  gip uses git diff HEAD~1 HEAD to find lines added or changed in the most recent commit. Existing marker comments from older commits will not be extracted. (To re-issue an old marker comment, you must edit or append to it to create a new diff).

• A block ends when the comments break

  It does not support blank lines or multi-line strings (like """ docstrings) within a block. The tool mechanically treats contiguous line comments (#) as a single block until the sequence breaks.

• Issue permalinks will 404 until pushed

  gip generates permalinks using your local HEAD commit hash. Therefore, links in newly created Issues will result in a "404 Not Found" until you push that commit to the remote (e.g., GitHub).

• Python only (for now)

  To avoid complexity, marker extraction is currently limited to Python (.py) files. Multi-language support may be added in the future.

• Execution context matters

  Make sure you run the command inside the target Git repository directory, as it relies on your local environment and Git configurations to access the destination.

• Branch names are just for reference

  gip does not perform any special magic to embed branch data into the Git commit history. It simply captures the active branch name at the exact moment the command is executed and records it as plain text in the Issue body.

• Labels must be created in advance

  As mentioned in the prerequisites, if the label does not exist on the platform side, it cannot be attached. Differences in behavior, such as failing to register with an error or creating the Issue without a label, strictly depend on the platform.

2. Executing the Command

After committing your code with marker comments, run the following command. By default, it will automatically pull your target name from your Git config (git config user.name).

gip

To extract comments for a different author name, use the --author flag:

gip --author "alice"

3. Platform and Destination Control (Environment Variables)

By setting environment variables, you can control the destination platform (GitHub/Gitea) for Issues and the label to be attached. We assume a workflow where you use tools like direnv to write environment variables into an .envrc file for each project (directory).

export GIP_REMOTE_TYPE=gitea
export GIP_REMOTE_URL=https://gitea.example.com/api/v1
export GIP_REMOTE_TOKEN=your_token_here
export GIP_LABEL=intent-memo

• GIP_REMOTE_TYPE: github or gitea (defaults to github if not specified).
• GIP_REMOTE_TOKEN: API access token.
• GIP_REMOTE_URL: The base URL of the API.
  • Required if TYPE=gitea (e.g., [https://gitea.example.com/api/v1](https://gitea.example.com/api/v1)). Undefined will cause an error.
  • If TYPE=github, it follows the specified URL (supports GitHub Enterprise). If not specified, it automatically infers from existing logic.
• GIP_LABEL: The name of the label to attach to the Issue. If not specified or left as an empty string, the Issue is created without attaching any label (no label).

🔄 The Ideal Workflow

Here is the most seamless and natural workflow for separating code from intent using git-intent-picker:

1. Write Code & Intent -> Commit (Finalize HEAD)

In your IDE, write your implementation along with your intent (marker comments) using # @name:, and commit them together. (e.g., git commit -m "feat: implement logic with intent")

2. Extract & Create Issues

Run gip. Marker comments are extracted from the latest commit diff, automatically creating Issues with perfect permalinks (using the finalized commit hash and exact line numbers).

3. Push to Remote (Enable Links)

Run git push. This pushes your commit to the remote repository, instantly validating the permalinks in your new Issues.

4. Clean up Intents (Detach the Sidecar)

Once the Issues are created, the inline marker comments are no longer needed. Delete them in your IDE and commit the cleanup as a separate step. (e.g., git commit -m "remove: gip marker comments") (You can do this manually, or let an AI agent naturally delete them during its next coding iteration).

This workflow guarantees a permanent snapshot of your design intent as an Issue while keeping your future codebase and commit history completely free of comment noise.

⚙️ Limitations

• Currently, the extraction target is strictly limited to files with the .py extension.

🤺 For Jujutsu (jj) Users: Fluid History and the "Wax Seal" Protocol

gip generates permalinks on the premise that a specific Git commit hash is "immutable." Therefore, its architecture fundamentally clashes with Jujutsu (jj), a tool that fluidly rewrites history and regenerates hashes as effortlessly as breathing.

However, when gip detects it is running in a jj environment, it automatically stamps Jujutsu's immutable identifier, the Change ID, into the footer of the Issue alongside the permalink. (e.g., 💎 jj Change ID: qzvqwsxv...)

To prevent permalinks from breaking (404) in a jj environment and to ensure gip functions correctly as an "Intent Sidecar," we recommend the following workflow.

📜 The Wax Seal Protocol

For Jujutsu users, executing gip is akin to the ritual of dropping a wax seal on a letter.

1. Shape the History: Use the powerful features of jj to freely rewrite, rebase, and perfectly sculpt your Change.
2. Attach the Intent: At the very last moment, when you decide "Okay, this is done," insert your marker comments in your editor.
3. Seal it (gip): Execute gip. The Git hash of that exact moment, along with the Change ID, is permanently stamped into the Issue.
4. Dispatch Immediately: Before the wax dries (i.e., before you make any other modifications that would vaporize the hash), immediately run jj git push to cast that hash into the remote .git database.

🩹 Recovering a Broken Seal (Manual Patching)

If you accidentally modify your code locally right after sealing it with gip, the underlying Git hash will be regenerated. Consequently, the permalink will become a 404 Not Found.

But don't worry—the Change ID left in the Issue acts as your ultimate fail-safe. If you want to restore the link, you can easily patch it manually:

1. Finish your final modifications and run jj git push to reflect the changes remotely.
2. Use jj log locally to retrieve the newly finalized Git commit hash.
3. "Edit" the Issue and manually replace the old hash in the URL with the new one.

Because the Issue is just editable text data, this simple manual recovery method allows gip to remain a pure, stateless "fire-and-forget" CLI tool without needing complex background state management.

License

This project is published under the MIT License.