# INTENT

## Project Name

**can-you-assist**

Short name / command name:

**cya**

---

## Purpose

`can-you-assist` exists to provide a command-line assistant interface for getting practical work done in the console with the help of large language models.

The project aims to make LLM-based assistance available directly where many technical users already work: in shells, repositories, local filesystems, notes, scripts, logs, and project directories.

Instead of requiring users to remember every option, flag, subcommand, file format, or tool-specific convention, `cya` should allow users to express intent in natural language and receive useful, context-aware help for command-line tasks.

The guiding idea is simple:

> Let the user ask for help at the console, let available LLM infrastructure provide the reasoning, and keep the memory, history, preferences, and adaptation under the user’s control.

---

## Primary Utility

`cya` provides a command-line tool that helps users interact with their local working environment through LLM-supported assistance.

It should support tasks such as:

- understanding files, folders, repositories, notes, and project structures;
- generating, explaining, improving, or transforming shell commands;
- assisting with code repository inspection and maintenance;
- helping with file-based workflows;
- summarizing and navigating textual content;
- providing context-aware hints without requiring users to remember detailed command syntax;
- adapting to user preferences, workflows, aliases, conventions, and recurring patterns over time.

The tool should act as a practical helper for console-based work, not as a replacement for the shell, editor, version control system, or specialized CLI tools.

---

## Core Motivation

Modern command-line environments are powerful but cognitively expensive.

Users often know what they want to achieve but do not remember:

- the exact command;
- the right flags;
- the safest invocation;
- the expected file format;
- the best tool for the job;
- the local project conventions;
- the accumulated context from previous related work.

LLM-based tools can help with this, but many existing systems centralize memory, history, adaptation, and workflow knowledge inside vendor-controlled applications.

`cya` should provide a user-controlled alternative:

- the user chooses or configures the available LLM backend;
- interaction history remains inspectable and portable;
- preferences and learned patterns are stored under user control;
- project-specific context can be managed locally;
- the tool can integrate with different LLM infrastructures instead of being locked to one provider.

---

## Intended Users

`cya` is primarily intended for users who work frequently in a terminal and want lightweight LLM assistance without leaving their local workflow.

Important user groups include:

- software developers;
- technical writers;
- repository maintainers;
- system operators;
- power users managing file-based notes and knowledge spaces;
- users working with many command-line tools but not wanting to memorize all details;
- users who want LLM assistance while keeping memory and adaptation portable and transparent.

---

## Primary Use Cases

### 1. Command Assistance

The user describes what they want to do, and `cya` suggests an appropriate command or sequence of commands.

Examples:

```bash
cya "find all markdown files modified this week"
cya "show me the git branches that are already merged"
cya "compress this folder but exclude node_modules"
````

The goal is not merely command generation, but safe, explainable, context-aware assistance.

---

### 2. Filesystem and Content Interaction

`cya` should help users work with local files and directories.

Examples:

```bash
cya "summarize the notes in this folder"
cya "find files that look like project plans"
cya "extract todos from these markdown files"
cya "compare these two config files"
```

The tool should be especially useful for text-heavy local workspaces such as code repositories, markdown notes, documentation trees, logs, and exported knowledge bases.

---

### 3. Code Repository Assistance

`cya` should help users inspect, understand, and work with code repositories.

Examples:

```bash
cya "what does this repo do?"
cya "where is the CLI entry point?"
cya "find likely places where authentication is handled"
cya "summarize recent changes"
cya "suggest a safe first refactoring step"
```

The project should support repository-aware context discovery without assuming one fixed project structure or language ecosystem.

---

### 4. Local Notes and Knowledge Work

`cya` should help users interact with file-based notes, project journals, markdown documents, and knowledge collections.

Examples:

```bash
cya "collect open decisions from these notes"
cya "turn this rough note into a project outline"
cya "find related notes about deployment"
cya "summarize what I worked on in this directory"
```

This use case is important because many users maintain valuable context in local text files rather than in centralized SaaS tools.

---

### 5. Personalized Console Helper

`cya` should adapt to the user’s habits over time.

It should be able to remember things such as:

* preferred command styles;
* preferred editors;
* shell conventions;
* repository conventions;
* naming preferences;
* common project types;
* preferred explanation depth;
* safety preferences;
* recurring workflows.

This adaptation should be implemented through user-controlled memory rather than opaque vendor-side personalization.

---

## Relationship to `llm-connect`

`cya` should use **llm-connect** as the abstraction layer for accessing LLM capabilities.

The purpose of this relationship is to keep `cya` independent from any single LLM provider, application, API, or runtime.

`llm-connect` should provide the connectivity layer for:

* selecting available LLM backends;
* sending prompts and context;
* receiving completions or structured responses;
* supporting different providers or local models;
* allowing users to configure their own LLM infrastructure.

`cya` should not hard-code one privileged LLM vendor as its conceptual foundation.

Instead:

> `cya` asks for assistance; `llm-connect` determines how available LLM infrastructure is reached.

---

## Relationship to `phase-memory`

`cya` should use **phase-memory** to provide memory, history, preferences, and adaptation under user control.

The purpose of this relationship is to separate assistant behavior from opaque application-managed memory.

`phase-memory` should support:

* storing interaction history;
* managing user preferences;
* capturing recurring workflows;
* maintaining project-specific memory;
* distinguishing global, local, temporary, and contextual memory;
* allowing users to inspect, modify, export, reset, or delete memory.

This is a core design principle:

> The user’s working memory should belong to the user, not to a vendor-owned assistant interface.

`cya` should therefore treat memory as a local or user-controlled capability, not as an invisible feature hidden behind a hosted product.

---

## Design Principles

### Console-Native

`cya` should feel natural in a terminal environment.

It should work well with:

* shell pipelines;
* current working directory context;
* local files;
* environment variables;
* git repositories;
* scripts;
* standard input and output;
* human-readable text;
* machine-readable output where useful.

---

### User-Controlled

The user should remain in control of:

* which LLM backend is used;
* what context is sent;
* what history is stored;
* what preferences are remembered;
* what project memory exists;
* when potentially destructive actions are executed.

`cya` should assist, not take over.

---

### Explainable and Inspectable

When `cya` suggests commands or actions, it should be possible to inspect what it is doing.

Important behaviors should be explainable:

* why a command was suggested;
* what files are being read;
* what context is being used;
* what memory influenced the answer;
* what risks may exist;
* what assumptions were made.

---

### Safe by Default

`cya` should avoid dangerous automatic execution.

Potentially destructive operations should require explicit user confirmation.

Examples include:

* deleting files;
* overwriting files;
* force-pushing git branches;
* changing permissions;
* running network-affecting commands;
* executing generated scripts;
* modifying many files at once.

The tool should prefer preview, explanation, and confirmation over blind execution.

---

### Backend-Agnostic

`cya` should not be tied to one assistant product.

It should be able to use different LLM infrastructures through `llm-connect`, including:

* hosted LLM APIs;
* local models;
* CLI-based LLM tools;
* organization-provided endpoints;
* future agentic runtimes.

The command-line interface should remain stable even if the underlying LLM infrastructure changes.

---

### Memory-Aware but Not Memory-Dependent

`cya` should become more useful through memory, but it should not require memory to function.

A first-time user should be able to use it immediately.

A long-time user should benefit from accumulated context, preferences, and workflow knowledge.

---

## Conceptual Architecture

At a conceptual level, `cya` consists of the following responsibilities:

### 1. CLI Interface

The command-line entry point used by the user.

Responsible for:

* parsing user input;
* identifying command modes;
* handling stdin/stdout;
* resolving current directory context;
* presenting results;
* asking for confirmation where needed.

---

### 2. Context Collector

Responsible for gathering relevant local context.

Possible sources include:

* current working directory;
* selected files;
* git status;
* repository metadata;
* configuration files;
* piped input;
* recent command history, where available and permitted;
* explicit user-provided context.

The context collector should be conservative and transparent.

---

### 3. Assistance Orchestrator

Responsible for turning user intent and collected context into a structured assistance request.

It decides:

* what kind of help is being requested;
* what context is relevant;
* whether memory should be consulted;
* whether the answer should be a command, explanation, patch, summary, or plan;
* whether safety checks are needed.

---

### 4. LLM Access Layer

Provided through `llm-connect`.

Responsible for:

* communicating with the selected LLM backend;
* abstracting provider differences;
* supporting configuration of available models and endpoints.

---

### 5. Memory Layer

Provided through `phase-memory`.

Responsible for:

* user preferences;
* project-specific memory;
* interaction history;
* workflow adaptation;
* reusable patterns;
* inspectable assistant state.

---

### 6. Safety and Confirmation Layer

Responsible for identifying risky actions and enforcing confirmation flows.

This layer should help prevent accidental damage caused by generated commands or misunderstood instructions.

---

## Expected Repository Role

This repository should contain the implementation and documentation for the `cya` command-line tool.

It should define:

* the CLI behavior;
* configuration model;
* integration points with `llm-connect`;
* integration points with `phase-memory`;
* prompt and context-handling conventions;
* safety rules;
* user-facing documentation;
* examples and workflows;
* tests for core command behavior.

---

## Out of Scope

The project should not initially aim to become:

* a full IDE;
* a full agentic coding environment;
* a vendor-specific LLM client;
* a replacement for Claude Code, Codex, shell tools, git, editors, or package managers;
* a centralized SaaS memory platform;
* an autonomous system that freely modifies the filesystem without confirmation;
* a general-purpose chatbot detached from console work.

`cya` may overlap with existing LLM console tools, but its intended differentiator is user-controlled, console-native assistance with portable memory and backend-agnostic LLM access.

---

## Initial Scope

The initial version should focus on a small but useful command-line assistant loop.

A reasonable first scope includes:

* a `cya` command that accepts natural-language requests;
* current-directory awareness;
* optional file input;
* optional stdin input;
* basic command suggestion;
* basic explanation mode;
* safe preview-first behavior;
* integration with `llm-connect`;
* simple integration with `phase-memory` for preferences and history;
* configuration file support;
* clear documentation of what context is sent to the LLM.

Example commands:

```bash
cya "what does this repo do?"
cya "suggest a command to find large files"
cya explain "tar -czf archive.tar.gz ./docs"
cya files "summarize these markdown files" README.md docs/*.md
cat error.log | cya "what is going wrong here?"
```

---

## Long-Term Direction

Over time, `cya` may evolve into a personalized command-line assistant substrate.

Possible future capabilities include:

* project-specific assistant profiles;
* reusable workflow recipes;
* local command learning;
* shell integration;
* repository indexing;
* structured task execution plans;
* safe patch generation;
* memory inspection and editing commands;
* team-shared memory packs;
* domain-specific helper plugins;
* integration with agentic coding tools;
* support for multiple concurrent LLM backends;
* transparent context and cost reporting.

The long-term ambition is not to create yet another closed assistant interface, but to provide a small, powerful, user-controlled bridge between local work and available LLM intelligence.

---

## Success Criteria

The project is successful if users can:

* get useful command-line help without remembering tool details;
* work more effectively with local files, notes, and repositories;
* choose their own LLM backend;
* inspect and control what context is used;
* preserve their own history and preferences;
* adapt the assistant to their workflows over time;
* avoid vendor lock-in for assistant memory and personalization;
* safely use LLM assistance in real console workflows.

---

## Mission Statement

`can-you-assist` gives users a console-native, backend-agnostic LLM helper that understands local work, remembers under user control, and helps get things done without requiring command-line trivia to be kept in human memory.