Syntax tracer comment < ISSUE_I D > < COMMEN T >
Description Adds a comment to an issue. Comments are stored in the event history and displayed when viewing issue details.
Arguments The ID of the issue to comment on (e.g., bd-1).
The comment text. Wrap in quotes if it contains spaces.
Options Output the updated issue in JSON format.
Examples Add simple comment
Implementation note
Blocker information
Progress update
Multi-line comment
Reference other issues
JSON output
tracer comment bd-5 "Working on this now"
Human-readable JSON (with —json flag) { "id" : "bd-5" , "title" : "Fix null pointer in parser" , "description" : "Parser crashes when input is empty or malformed" , "design" : "" , "acceptance_criteria" : "" , "notes" : "" , "status" : "in_progress" , "priority" : 0 , "issue_type" : "bug" , "assignee" : "agent-1" , "estimated_minutes" : null , "created_at" : "2026-03-02T14:30:00Z" , "updated_at" : "2026-03-04T11:30:00Z" , "closed_at" : null , "external_ref" : null , "dependencies" : [] }
Issue not found Error: Issue bd-999 not found
Comments are displayed when showing issue details:
bd-5 Fix null pointer in parser [P0, bug] Status: in_progress Assignee: agent-1 Created: 2026-03-02 14:30 | Updated: 2026-03-04 11:30 Description: Parser crashes when input is empty or malformed Recent comments: agent-1 (just now): "Fixed by adding null checks" human-dev (2 hours ago): "This is blocking deployment" agent-1 (5 hours ago): "Found the root cause in tokenizer"
Use Cases For AI Agents # Log implementation approach tracer comment bd-5 "Using strategy pattern to handle different input types" # Document discovered issues tracer comment bd-5 "Found edge case: empty arrays not handled" # Track progress tracer comment bd-5 "Completed implementation, writing tests" # Note blockers tracer comment bd-5 "Waiting for API documentation before proceeding"
For Human Collaboration # Provide context tracer comment bd-10 "This affects the production deployment scheduled for Friday" # Ask questions tracer comment bd-7 "Should we support legacy format or migrate everything?" # Share findings tracer comment bd-12 "Reproduced on staging, root cause is rate limiting"
Comments include the actor name and timestamp automatically. Use $TRACE_ACTOR environment variable to set your identity: export TRACE_ACTOR = "agent-name" tracer comment bd-5 "Starting work"
Comments are particularly useful for:
Recording implementation decisions
Noting blockers and their resolution
Documenting edge cases discovered during work
Providing status updates for long-running tasks
Sharing context with other team members or agents
Use tracer show <id> --full to see the complete comment history along with all other events. 
