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

### Recommended: Install from Development Head (Latest Code)

This is the easiest way to stay on the absolute latest version while you work:

```bash
git clone https://github.com/worsch/can-you-assist.git
cd can-you-assist

# One-command developer install (includes dev tools)
make dev-install

# Or manually:
# pip install -e ".[dev]"
```

This installs the package in editable mode from your local checkout. You will always get the newest code when you pull.

After installation:
```bash
cya --help
cya --version   # Will show a development version (e.g. 0.2.0.devN+g...)
```

### Alternative: Install Directly from Git (No Local Clone)

You can also install the latest code directly from GitHub without cloning first:

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

This is useful for quick testing or on remote machines.

### For Future Released Versions

Once we publish packages (future work), you will be able to do:

```bash
pip install can-you-assist
```

or a specific version:

```bash
pip install "can-you-assist>=0.3.0"
```

### Updating to Latest Development Code

```bash
cd can-you-assist
git pull
pip install -e ".[dev]"   # or just `make dev-install`
```

## 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 + 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.

```bash
# 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:
```bash
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.

```bash
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:
```bash
~/.config/cya/memory/<scope>.json
```

Useful commands:
```bash
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

```bash
# 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`