Skip to content

cli.md

Latest commit

 

History

History
463 lines (318 loc) · 19.4 KB

cli.md

File metadata and controls

463 lines (318 loc) · 19.4 KB
Raw

CLI

The Awareness Framework CLI is an optional helper. The framework does not require a tool, but the CLI reduces how much methodology an agent must keep in context.

Instead of asking every agent to remember the full protocol, use commands that check and maintain private files.

Install

npm install -g @fyso/awareness-framework

See Install for first-run setup, wrapper initialization, updates, and custom paths.

For local development:

npm install
npm test
npm link

Private State

By default, commands use:

~/.agents/

Override with:

awareness status --home /path/to/private/agents

or:

AGENTS_HOME=/path/to/private/agents awareness status

Use channel-scoped state for multi-channel integrations:

awareness status --channel support

This resolves to:

~/.agents/channels/support/

Use --agent-folder as a clearer alias when the path is a base folder:

awareness status --agent-folder /path/to/agents --channel support

User memory is narrow and separate from the channel context. It lives under memory/users/ inside the selected channel or base folder.

Session Bootstrap vs Operational Refresh

Instruction-file imports are a bootstrap mechanism. They can load a snapshot of current.md at session start, but they do not guarantee that an agent sees updates made later by another agent.

Use the CLI as the operational refresh and maintenance layer:

  • At session start, run awareness status or awareness check when the CLI is available.
  • If the session may be stale because another agent worked in parallel, run awareness refresh.
  • Before handoff, run awareness handoff or awareness check.
  • When changing state, prefer awareness focus and awareness log over manual edits.

If the CLI is not available, read ~/.agents/awareness/current.md directly.

Commands

init

Creates the private directory structure and starter files if they do not exist.

awareness init

Creates:

  • AGENTS.md
  • awareness/current.md
  • worklog/YYYY-MM-DD.md
  • memory/personality.md
  • memory/preferences.md
  • memory/patterns.md
  • memory/long-term.md
  • evaluations/
  • runtime/

Create regular wrapper files for Codex, Claude Code, OpenCode, and Pi:

awareness init --wrappers

Existing wrappers are preserved. To replace them intentionally:

awareness init --wrappers --overwrite-wrappers

Use custom roots for tests or non-standard machines:

awareness init --wrappers \
  --home /path/to/.agents \
  --user-home /path/to/user-home \
  --config-home /path/to/config-home

update

Applies non-destructive template additions to existing private state.

awareness update --dry-run
awareness update

Use this after upgrading the CLI when templates gained new guidance, or run awareness init again for the same non-destructive reconciliation. It preserves current focus, worklogs, durable memory, candidates, and event history. It only adds known missing sections or lines, such as new memory effectiveness guidance in AGENTS.md and memory/long-term.md.

status

Shows the current focus, the detected session context, and warnings. Warnings are printed but do not make the command fail; use awareness check --strict when automation should fail on warnings.

awareness status

Session Context is derived from git in the working directory (owner/name from the origin remote when present, otherwise the worktree directory name, plus the current branch). It is never written back over Current Focus.

When the two disagree, status says so instead of asserting the stored value:

Current Focus
- Task: ETENDORX-BUILD-SPEED
- Repository: etendo_rx
- Branch: feat-speed

Session Context
- Repository: fyso-dev/awareness-framework
- Branch: main
- Note: Current Focus (etendo_rx / feat-speed) diverges from session context (fyso-dev/awareness-framework / main).

Repositories are compared on the trailing path segment, so fyso/ingest and fyso-dev/ingest count as the same repo. Outside a git worktree no session context is shown and no divergence is claimed.

The same divergence notice is added to the context that hook run injects at session start and on each user prompt, so an agent is told the stored focus may not apply rather than adopting it silently.

A Setup section lists environment gaps (for example, an unconfigured memory trigger). These are kept separate from board warnings and never feed the evaluation diagnostics that generate memory promotion candidates.

refresh

Reloads the awareness board from disk and prints the current status. This is an alias for status with a name that makes the cross-agent refresh intent explicit.

awareness refresh

check

Checks whether private state is maintainable.

awareness check
awareness check --strict

Use --strict in automation when warnings should fail the command.

focus

Updates Current Focus, upserts the task in Active Tasks, and appends a worklog entry.

awareness focus \
  --task PROJECT-123 \
  --summary "Agent awareness framework" \
  --repo fyso-dev/awareness-framework \
  --branch codex/cli-and-personality \
  --state in-progress \
  --next "Run tests and open a PR"

Valid states are started, in-progress, paused, blocked, waiting, done, in-review, and ready. Underscore aliases such as in_progress and in_review are accepted and normalized.

--repo and --branch default to the detected git context, so they can be omitted inside a worktree. Explicit flags always win. Outside a git worktree they fall back to Unspecified.

A task block records Done only when real work has been logged against it, and existing Done entries survive later focus switches.

log

Appends a concrete progress entry to the daily worklog, and appends --changes to the matching task's Done list on the board. If no task block matches, the board is left untouched rather than inventing one.

awareness log \
  --task PROJECT-123 \
  --summary "Added CLI helper" \
  --changes "Implemented init, status, check, focus, log, handoff, evaluate, and personality commands." \
  --evidence "src/cli.js"

archive

Retires State: done task blocks from Active Tasks into awareness/archive/YYYY-MM.md, keeping the board (which is injected into every session) down to work that is actually live.

awareness archive --dry-run
awareness archive

The task named by Current Focus is never retired, even when done: removing it would leave the focus pointing at a task with no detail on the board.

handoff

Prints a handoff snapshot from the awareness board. Like status, warnings are informational and return exit code 0.

awareness handoff

evaluate

Builds a private daily evaluation note using simple heuristics.

awareness evaluate
awareness evaluate --print
awareness evaluate --force

When an evaluation is written, the CLI also records low-risk promotion candidates in memory/long-term.md. It does not silently promote candidates into durable rules; use awareness memory promote after review.

memory

Reviews and promotes long-term memory.

awareness memory show
awareness memory candidates
awareness memory review
awareness memory review --min-count 3
awareness memory note --text "User prefers active memory review" --evidence "Direct request"
awareness memory promote --kind preference --text "Surface memory candidates proactively" --evidence "User confirmed"
awareness memory used --text "Prefer recall before repeating implementation work" --note "Saved a duplicate effort"
awareness memory used --key a1b2c3 --note "The curated entry directly informed this fix"
awareness memory stats --since 7d
awareness memory stats --since all --json
awareness memory stats --since 30d --snapshot
awareness memory trigger --phase pre-action --action "npm publish"

memory show prints the curated long-term memory (Preferences, Patterns, Project Conventions, Review Guidance) grouped by section. Empty sections, raw promotion candidates, and pruned or revised entries are omitted, so it is a quick read-only view of what is actually durable.

memory review scans promotion candidates and suggests repeated candidates as pattern promotions once they appear at least twice by default.

memory candidates lists active promotion candidates only. Text that has been pruned or revised remains in the Markdown history but is hidden from active candidates, excluded from suggestions, and rejected by memory promote.

Valid promotion kinds are preference, pattern, project, and review.

memory used credits a curated long-term entry that actually helped a task. Use --text to match by content or --key to target the deterministic entry key shown in memory stats --json; add an optional --note to explain why the memory mattered. Each use appends a memory.used event to memory/events.jsonl with the matched key, the curated text, and the note.

memory stats summarizes whether stored memory is healthy, utilized, and useful. The command accepts --since today, --since 7d, --since 30d, or --since all, prints text by default, emits machine-readable JSON with --json, and appends the aggregate snapshot to runtime/metrics/YYYY-MM-DD.jsonl with --snapshot.

memory trigger asks a configured AI trigger provider whether the current phase/action/message should recall local memory. It does not use keyword rules.

The provider is resolved from AWARENESS_MEMORY_TRIGGER_COMMAND first, then from memoryTriggerCommand in <home>/config.json. awareness memory setup writes that config entry, so the trigger is active immediately without a shell-profile change; the environment variable still overrides it per shell. Until a provider is resolved, recall never runs — status and check report this under Setup, and stats counts those calls as provider not configured rather than as evaluations, so a disabled trigger does not read as "evaluated and found nothing useful".

The executable reads a JSON context from stdin and returns JSON:

{
  "shouldRecall": true,
  "confidence": 0.87,
  "intent": "release conventions and local CLI update requirements",
  "reason": "The next action is a release, where prior project rules may affect behavior.",
  "risk": "high",
  "model": "gpt-5.4-mini"
}

If no provider is configured, the trigger records a skipped decision instead of guessing from keywords and does not charge internal decision tokens. Provider calls are bounded by AWARENESS_MEMORY_TRIGGER_TIMEOUT_MS (default 3000) and fail closed as skipped decisions. Trigger output is token-accounted: internal decision/retrieval tokens are separated from injected context tokens, and context overhead is computed against AWARENESS_CONTEXT_BUDGET_TOKENS (default 128000). Retrieval injects only curated long-term memory sections plus recent worklog context, so inactive promotion candidates and pruned audit entries are not resurrected as durable memory.

memory debug reads optional trigger debug traces from runtime/memory-debug/YYYY-MM-DD.jsonl. Debug logging is off by default. Set AWARENESS_MEMORY_DEBUG=summary to record input, deduction, retrieval candidates, injected keys/text, and token accounting. Set AWARENESS_MEMORY_DEBUG=full (or 1) to also store the full provider transcript context: phase, text/action, current focus, current context, bounded long-term memory, recent worklog text, raw provider decision, candidate list, and injected context. Full debug can contain private transcript and memory content, so use it intentionally and keep it local.

AWARENESS_MEMORY_DEBUG=summary awareness memory trigger --phase message --text "how do we publish this?"
AWARENESS_MEMORY_DEBUG=full awareness memory trigger --phase pre-action --action "npm publish"
awareness memory debug --since today
awareness memory debug --last 5 --json
awareness memory debug --watch --interval 1000

Reported levels:

  • Store health — conversion from candidates to durable memory, source mix, churn, density, and freshness indicators.
  • Utilization — how often curated entries are recalled, which entries are workhorses, dead-weight entries that were never recalled, recall rate per session, and repeated zero-result queries as the gap detector.
  • Outcome — how often recalled entries are later credited with memory.used, plus contradictions or stale signals around those credited entries.
  • Scorecard — a composite summary that rolls the levels into a quick read on activation, precision, outcome, freshness, and overall usefulness.

runtime/recall/YYYY-MM-DD.jsonl records the usage side of recall, including curatedHits when the recall matched curated long-term entries. curatedHits is an array of deterministic entry keys, so the same key can be attributed across multiple recalls without depending on line numbers or text formatting. Older recall events may not have this field; those rows simply count as unattributed history.

Local memory operations

These commands provide a small Cognee-inspired operation vocabulary without adding a graph database or vector store.

awareness remember --text "Prefer recall before repeating implementation work" --evidence "User request"
awareness recall "implementation work"
awareness forget --text "Old assumption" --reason "Superseded by user correction" --evidence "Correction message"
awareness improve

remember records a promotion candidate and appends memory.candidate.created to memory/events.jsonl. recall performs local text search across memory, memory events, worklogs, and evaluations using an in-memory MiniSearch index. Matching is case- and accent-insensitive, supports prefix/fuzzy matches, preserves local-only privacy, and still includes a small curated alias set for common English/Spanish memory terms. forget records a prune/revision entry and appends memory.pruned; it does not destructively delete historical evidence, but pruned text is inactive for candidate review and promotion. improve runs the evaluation/review loop and appends evaluation.created and pattern.suggested events when applicable. Auto-generated evaluation candidates are deduplicated by text across days so recurring diagnostics do not flood human-curated candidates.

recall also appends a usage event to runtime/recall/YYYY-MM-DD.jsonl (source, query, terms, resultCount, topFiles, and curatedHits when available). These hits feed the recall metrics in awareness stats; queries with resultCount: 0 highlight memory gaps.

stats

Aggregates the events and state the CLI already records into a usage report. It is read-only over the local private state and never posts anywhere.

awareness stats                       # default window: last 7 days
awareness stats --since today
awareness stats --since 30d
awareness stats --since all
awareness stats --json                # machine-readable for dashboards/pipelines
awareness stats --snapshot            # also append the aggregate to runtime/metrics/YYYY-MM-DD.jsonl

Reported metrics:

  • Sessions & hooks — sessions started, total hook events, compactions, and a per-tool breakdown (from runtime/hooks).
  • Scheduled runs — counts by cadence and the warnings trend (from runtime/schedule).
  • Memory — candidates created (by source), promotions (by kind), prunes, and pattern suggestions (from memory/events.jsonl).
  • Recall (hits) — calls, average results per call, zero-result queries, repeated zero-result queries, and the most frequent queries and matched files (from runtime/recall).
  • Memory Trigger — AI trigger calls, injected/skipped decisions, phase/provider breakdown, an efficiency KPI, injected token totals, internal decision token estimates, and context overhead percentage. The KPI stays in learning until useful injected memory is credited with awareness memory used; after that it scores credited injection rate against context overhead.
  • Activity — worklog entries, distinct tasks, and distinct repositories in the window (from worklog/*.md).
  • Storage — file count and bytes per area, computed on demand.

--snapshot persists the full aggregate as one JSON line per run, giving a time series for growth charts without recomputing history. --since accepts today, 7d, 30d, or all; window filtering is by date so partial-day boundaries are inclusive of the whole day.

hook run

Records a lightweight lifecycle event from an agent CLI hook.

awareness hook run --tool codex --event session-start
awareness hook run --tool claude --event pre-compact --quiet
awareness hook run --tool opencode --event session.idle

This writes JSON lines under:

~/.agents/runtime/hooks/YYYY-MM-DD.jsonl

Hook events do not append to the daily worklog. Use awareness log for human-relevant progress.

hook install

Installs supported hook integrations.

awareness hook install --tool all --command "$(command -v awareness)"
awareness hook install --tool codex --command "$(command -v awareness)"
awareness hook install --tool claude --command "$(command -v awareness)"
awareness hook install --tool opencode --command "$(command -v awareness)"

Generated files:

  • ~/.codex/hooks.json
  • ~/.claude/settings.json
  • ~/.config/opencode/plugins/awareness-framework.js

Use an absolute --command path when hooks run outside an interactive shell.

For OpenCode, --overwrite replaces an existing non-generated plugin file. Use it only when that file is intentionally managed by this framework.

schedule run

Runs periodic maintenance.

awareness schedule run --cadence hourly
awareness schedule run --cadence daily

Hourly runs record warnings under runtime/schedule/. Daily runs also create evaluations/YYYY-MM-DD.md if it does not exist.

schedule install

Installs macOS LaunchAgents for global periodic execution.

awareness schedule install --cadence all --command "$(command -v awareness)"
awareness schedule install --cadence all --command "$(command -v awareness)" --load

Generated files:

  • ~/Library/LaunchAgents/dev.fyso.awareness.hourly.plist
  • ~/Library/LaunchAgents/dev.fyso.awareness.daily.plist

See Hooks and Scheduling for tool-specific notes.

user show

Shows narrow memory for a user. If --channel is provided, memory is read from that channel's private state.

awareness user show --user user-123
awareness user show --channel support --user user-123

user note

Appends a small evidence-backed fact about a user.

awareness user note \
  --channel support \
  --user user-123 \
  --kind question \
  --text "Asked how worklog automation should be organized" \
  --evidence "Message link or timestamp"

Supported kinds:

  • nickname
  • question
  • topic
  • preference
  • fact
  • note

User notes do not create a full awareness workspace for that user. Channel context remains in awareness/ and worklog/; user memory remains in memory/users/<user>.md.

Personality Commands

Personality is stored privately in ~/.agents/memory/personality.md.

awareness personality show
awareness personality note --text "User prefers concise Spanish status updates" --evidence "Repeated feedback"
awareness personality adopt --text "Use direct, pragmatic Spanish for work updates" --evidence "User confirmed preference"

Candidate observations are cheap to record. Accepted traits should come from repeated evidence or explicit user confirmation.