can-you-assist/README.md

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

1. Install from Development Head (Recommended for Daily Use)

Stay on the absolute latest code with one command:

git clone https://github.com/worsch/can-you-assist.git
cd can-you-assist
make dev-install

Or the direct git method (no permanent clone needed):

pip install "git+https://github.com/worsch/can-you-assist.git@main#egg=can-you-assist[dev]"

After installing, cya --version will show a development version (e.g. 0.2.0.dev48+gf500a35...).

2. Install a Released Version (Future)

Once we publish official releases:

pip install can-you-assist
# or a specific version
pip install "can-you-assist>=0.3.0"

See docs/release-process.md for how releases are cut.

Updating

cd can-you-assist
git pull
make dev-install

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 (Profile 1 spike in T05 adds optional verbal lesson capture at the end):

• 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).
• Current implementation is formally Profile 0 (post-0003 local JSON + activation + retrospection loop). See CYA-WP-0005 and the "Profile 0 Baseline" section in MemoryVision.md for the exact definition and the roadmap to Profiles 1–3 (self-improving verbal reflections, hierarchical synthesis, and procedural rules).

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

# Recommended one-liner (see Installation section above)
make dev-install

pytest tests/ -q
cya "..."   # manual verification
make version   # show current dev version

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