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 (FakeLLMAdapter by default; real llm-connect when configured)

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

LLM backend (configured vs offline)

By default cya uses a deterministic offline adapter (no API keys, no network). For real inference, configure llm-connect:

# 1. Install llm-connect (sibling checkout)
pip install -e ~/llm-connect

# 2. Route credentials — do not commit keys
warden route find "OpenRouter API key" --json

# 3. Export key and configure cya
export OPENROUTER_API_KEY="..."   # from OpenBao / operator path
mkdir -p ~/.config/cya
cat > ~/.config/cya/config.toml <<'EOF'
[llm]
adapter = "connect"
backend = "openrouter"
model = "anthropic/claude-sonnet-4"
EOF

cya "show me the recent git history for this repo"

Force offline mode anytime (tests, CI, air-gapped):

cya --offline "your request"
# or: CYA_LLM_ADAPTER=fake cya "..."

See docs/llm-connect-integration.md for the full mapping, session context budget, and optional .cya.toml project overrides.

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").
• Optionally capture 1–3 verbal lessons (Profile 1) with guided prompts, preview, and confirmation.

Example Profile 1 flow at the end of cya retrospect:

Capture 1–3 verbal lessons from this session? (y/n) y
What went well that you want to remember? (or 'skip') Safety warnings were clear
What should cya remember for next time? (or 'skip') Always suggest git status first
What should cya avoid in this scope? (or 'skip') skip

Preview — verbal lessons to save
1. [went well] Safety warnings were clear
2. [remember] Always suggest git status first

Save these lessons? (y/n) y
Saved 2 verbal reflection(s) (Profile 1).

These goals and lessons are stored as first-class 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
cya memory reflections            # List verbal reflections for the current scope
cya memory reflections --json     # Export reflections as JSON
# (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).
• Profile 0 (post-0003 local JSON + activation + retrospection loop) is the stable foundation.
• Profile 1 (verbal reflections) is production-ready as of CYA-WP-0006: guided capture in cya retrospect, cya memory reflections, compaction, and surfacing in responses / --explain-context.
• Profiles 2–3 (hierarchical synthesis, procedural rules) remain roadmap items — 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

# Recommended one-liner (see Installation section above)
make dev-install
pip install -e ~/llm-connect   # optional, for live inference

pytest tests/ -q               # offline mocks only; no API keys
pytest -m llm_live             # manual live check (requires OPENROUTER_API_KEY)
cya --offline "..."            # manual verification without network
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