/ 
App-karr-0.601
/ App::karr::Cmd::Context

NAME

App::karr::Cmd::Context - Generate board context summary for embedding

VERSION

version 0.601

SYNOPSIS

karr context
karr context --sections blocked,overdue
karr context --write-to AGENTS.md --days 14
karr context --activity-limit 10
karr context --json
karr context --compact

DESCRIPTION

Builds a concise board summary suitable for embedding into agent context files such as AGENTS.md. The command can print Markdown directly, emit structured JSON, or update an existing file between sentinel comments.

--compact prints the board's four numbers and nothing else -- one key=value per line, under the same names the --json summary uses, with no headings, no sections and no sentinels:

board_name=karr
total_tasks=41
active=7
blocked=1
overdue=0

That is the reading of a briefing that fits in a prompt header or a status line, and it is what context --compact was silently failing to do while --compact was declared for every command in App::karr::Role::Output (#254). It shapes what is printed, not what is written: with --write-to the file still receives the Markdown block, because those sentinels are an interop contract with kanban-md (see "FILE UPDATE MODE") and a compacted block would be one neither tool could find again.

--json and --compact do not compete with --write-to and never did (#260). --write-to is a side effect; the output flags decide what stdout carries. All three combinations write the same Markdown block to the file and differ only in what is printed:

karr context --write-to AGENTS.md              Context written to AGENTS.md
karr context --json    --write-to AGENTS.md    the JSON payload
karr context --compact --write-to AGENTS.md    the four numbers

With an output flag the Context written to ... confirmation goes to stderr, so karr context --json --write-to AGENTS.md > ctx.json leaves behind a file that decodes whole -- the channel rule delete's prompt follows for the same reason (#248). Without one, stdout is prose anyway and the line stays there.

Only archived tasks are left out of the summary: finished work still counts towards the reported total, the rule kanban-md applies to the same block. One number deliberately diverges -- a card in a terminal status is not counted or listed as blocked here even when its flag is still set, because a done card is not an active blocker (tickets #229, #295). Its block_reason stays on the card as provenance and karr list --blocked --status done still finds it.

SECTIONS

The generated context can include in-progress, blocked, overdue, recently-completed, and activity. Use --sections with a comma-separated list to limit the output to a subset.

activity is the board's activity log (see App::karr::Cmd::Log), filtered to entries written by identities other than the one invoking context and bounded by --activity-limit (default 5). An agent reading its own briefing already knows what it just did -- karr show --me is the tool for that -- so what belongs in a briefing is what everyone *else* has been doing.

recently-completed looks back --days days (default 7) from now; a task qualifies when its completed stamp falls on or after that cutoff, compared to day granularity rather than to the second so the comparison stays correct whether the stamp is a bare YYYY-MM-DD or a full RFC3339 timestamp.

FILE UPDATE MODE

When --write-to is used, the command replaces the content between BEGIN kanban-md context and END kanban-md context if those sentinels are already present; otherwise it appends the generated block to the file. A file that does not exist yet is created carrying the block alone.

It is a file update and not a redirection: the rest of the host file is left as it was, and a later run rewrites the same block in place rather than adding a second one. That is why the block is always Markdown, whatever --json or --compact ask for on stdout -- both tools find their block by these sentinels, and a payload between them is one neither could update again.

SEE ALSO

karr, App::karr, App::karr::Cmd::Board, App::karr::Cmd::List, App::karr::Cmd::Config, App::karr::Cmd::Skill, App::karr::Cmd::Log

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/karr/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)