can-you-assist/INTENT.md

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:

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:

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:

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:

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:

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.