Annotation

Blackbox can annotate your repository for you.

From the workflow card in the dashboard, you can start an annotation flow that connects a GitHub repository and opens a pull request with deterministic Blackbox-related changes.

Supported Annotation Libraries

• LangGraph: AgentIR-langgraph on GitHub 
• AI SDK: AgentIR-AI-SDK on GitHub 

These are the libraries Blackbox adds when it can confidently map your code to supported patterns.

What The Annotator Does

When you start annotation from the dashboard:

1. Blackbox binds your Blackbox API key and Blackbox base URL to the repo setup flow.
2. You install or authorize the GitHub App for the target repository.
3. Blackbox scans the repository source text and plans deterministic annotation changes.
4. Blackbox opens a PR instead of pushing directly to your default branch.

What The PR Can Change

Depending on the framework it detects, the PR can:

• add the Blackbox annotation dependency
• add imports such as llm_call, writes, GraphProxy, defineAgentIRTool, defineToolLoopAgent, or llmCall
• wrap or annotate supported LLM call sites so they become compile-visible
• add .agentir/ANNOTATION_PLAN.md with review notes
• add agentir.config.json
• add .github/workflows/agentir-compile.yml
• add a managed local CLI package under .agentir/cli for compile bootstrap

The exact diff depends on what Blackbox can prove safely from your codebase.

What The Annotator Will Not Do

• it does not execute your cloned repository code
• it does not merge to your branch automatically
• it does not silently rewrite unsupported patterns
• it does not force a code-changing PR when the final audit is not safe enough

If the code changes are not safe enough to ship automatically, Blackbox can open a plan-only PR that contains the markdown review artifact without touching runtime code.

Repository Secrets And Variables

As part of compile bootstrap, Blackbox configures repository-level GitHub Actions settings for the workflow:

• BLACKBOX_API_KEY
• BLACKBOX_URL

BLACKBOX_API_KEY authenticates the compile request for your workflow. BLACKBOX_URL tells the managed compile workflow which Blackbox deployment to call. That lets the workflow recompile the annotated repo without hardcoding secrets into source control.

What You Should Review In The PR

Review the PR the same way you would review an internal codegen or codemod PR:

• confirm the annotated nodes match real LLM call sites
• confirm the model ids are correct
• confirm the compile-visible entry points match the workflow you intend to run
• confirm the dependency and workflow file additions fit your repo conventions

When To Use Annotation

Use the dashboard annotation flow when you want the fastest adoption path and prefer reviewing a PR over adding wrappers and decorators manually.

If you want to author the integration yourself, continue to Agent Skills, LangGraph, or AI SDK.