generated from coulomb/repo-seed
111 lines
3.8 KiB
Markdown
111 lines
3.8 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
git clone <this-repo>
|
|
cd can-you-assist
|
|
pip install -e .
|
|
cya --help
|
|
```
|
|
|
|
## Usage examples
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
`cya` has real, user-controlled memory for preferences and workflow patterns.
|
|
|
|
```bash
|
|
# Remember something for this directory / project
|
|
cya "remember that I prefer to see git status --short --branch by default"
|
|
|
|
# Later, in the same directory, cya will recall it without you restating
|
|
cya "what is my preferred git view?"
|
|
|
|
# You can always inspect or clear what is stored
|
|
cya --explain-context "..." # shows memory provenance
|
|
# The backing files live in ~/.config/cya/memory/ (plain JSON, fully user-editable)
|
|
```
|
|
|
|
Memory signals also feed the safety layer: a standing "never auto-run" preference will still force mandatory confirmation even for commands the rules might otherwise treat more leniently.
|
|
|
|
All memory usage is visible and explainable. Nothing is hidden or opaque.
|
|
|
|
See:
|
|
- `src/cya/memory/__init__.py` (the explicit seam)
|
|
- `workplans/CYA-WP-0002-memory-integration-roadmap.md`
|
|
- `MemoryVision.md` for the longer-term direction (profile-driven phase-memory)
|
|
|
|
## 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
|
|
|
|
```bash
|
|
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`
|
|
|