cya — console-native assistant for local work

cya lets you express intent in natural language from your terminal and receive safe, explainable, context-aware help.

It is the CLI surface for the capabilities domain. It owns orchestration, the user experience, and the safety layer. It talks to llm-connect only through a stable adapter boundary and keeps all memory under explicit user-controlled ports (implemented by phase-memory).

Status

This is the first narrow MVP slice (CYA-WP-0001). The tool is already usable after pip install -e .:

• cya "your request in plain English"
• cya --explain-context "..." — shows exactly what local context would be sent
• Automatic rule-based risk classification with mandatory confirmation for anything destructive, privileged, mass-edit, or network-affecting
• All LLM interaction flows through a documented LLMAdapter seam (currently a deterministic fake; ready for real llm-connect)

Installation (development)

git clone <this-repo>
cd can-you-assist
pip install -e .
cya --help

Usage examples

# Normal request (safe path)
cya "show me the recent git history for this repo"

# Risky request — will show classification + require explicit confirmation
cya "delete every log file older than 30 days in this tree"

# See exactly what context would be collected and sent
cya --explain-context "explain the changes in the last commit"

The output includes a structured suggestion, rationale, and (when relevant) a clear preview + confirmation prompt. Nothing executes without your explicit yes.

Safety (core product behavior)

• Genuine rule-based assessment is the primary mechanism.
• Results are available to the model.
• Anything above "safe" produces a preview and blocks until you confirm in the launching terminal.
• No autonomous execution in this slice.

See the risk classifier tests and workplan T03 for the exact rules and invariants.

Memory (T02 + T03 + T04 + 0003)

cya has real, user-controlled, context-aware memory that improves over time.

Automatic Directory/Project-Bound Activation (T03)

Memory scoped to a directory or project is automatically activated when you work there.

# In your project directory, teach cya your preferences once
cya "remember that I always want the short git status with branch info"

# Later, in the same directory (or any subdirectory), cya will use it automatically
cya "show me the recent changes"

# No need to restate your preference — it is activated based on the working directory

See exactly what memory influenced a response:

cya --explain-context "show me the recent changes"

Structured Retrospection & Continuous Improvement (T04)

Run a guided reflection session to review how memory was used and explicitly set goals for future interactions.

cya retrospect

During the session cya will:

• Show recent memory items that were activated.
• Help you reflect on what worked or didn't.
• Let you record new interaction goals (e.g. "be more concise", "always show one safe alternative for destructive commands").

These goals are stored as first-class retrospection memory and will influence future activations and responses.

Inspecting and Controlling Memory

All memory is stored in plain, user-editable JSON:

~/.config/cya/memory/<scope>.json

Useful commands:

cya --explain-context "..."     # See exactly what memory was activated and why
# (You can also use the memory ports directly in Python if you want to script it.)

Memory also feeds the safety layer: a "never auto-run" preference you set during retrospection will still force mandatory confirmation.

Architecture Notes

• Memory lives behind explicit ports in src/cya/memory/__init__.py.
• Activation is automatic based on cwd + git root (with full provenance).
• Retrospection outcomes are stored with special kinds (retrospection, interaction_goal) and get preferential treatment in future context building.
• Everything is designed to be replaced/enriched by a full phase-memory implementation later (see MemoryVision.md).

See:

• docs/cya-memory-activation-and-retrospection-concept.md (the T01 design)
• workplans/CYA-WP-0003-...md
• src/cya/memory/__init__.py
• MemoryVision.md for the long-term phase-memory vision

All memory usage is visible, explainable, and under your control. Nothing is hidden or opaque.

Architecture & boundaries (important)

• can-you-assist (this repo): CLI, context collection, safety, orchestration.
• llm-connect: Provider access, config, token counting, structured responses. All interaction goes through cya/llm/adapter.py (LLMAdapter Protocol).
• phase-memory: Durable, user-controlled memory. Real (persisting) implementation lives behind the explicit ports in cya/memory/__init__.py (T02). Signals also flow into the rule-based risk layer (T04).

See workplans/CYA-WP-0001-console-native-mvp.md for the full task breakdown, decisions, and integration guide.

Development

pip install -e .
pytest tests/ -q
cya "..."   # manual verification

License

MIT (see LICENSE).

Workplan & coordination

• Workplan: workplans/CYA-WP-0001-console-native-mvp.md
• State Hub workstream: repo-integration-can-you-assist
• Operator reminder after changes: cd ~/state-hub && make fix-consistency REPO=can-you-assist