/ 
App-karr-0.600
/ App::karr::Cmd::Context

NAME

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

VERSION

version 0.600

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 and is still reported as blocked if it is, which is the rule kanban-md applies to the same block.

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)