mirror/QodeAssist
1
0
Fork 0
mirror of https://github.com/Palm1r/QodeAssist.git synced 2026-07-23 19:51:05 -04:00
Code Issues Packages Projects Releases Wiki Activity

feat: add support acp in common chat (#369)

Browse Source
This commit is contained in:
Petr Mironychev
2026-07-21 13:10:00 +02:00
committed by GitHub
parent af85efb554
commit 442263a6a7
158 changed files with 14270 additions and 4118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
docs/acp-agents.md Normal file
View File

@@ -0,0 +1,114 @@
# ACP agents
QodeAssist can talk to external coding agents that speak the
[Agent Client Protocol](https://agentclientprotocol.com) (ACP). The **QodeAssist >
Agents** settings page lists the agents it knows about and lets you verify that one
starts and answers the ACP handshake.
## Where the list comes from
The list is merged from three sources. When the same agent `id` appears in more than
one, the higher entry wins:
1. **Your JSON files** in `qodeassist/agents/` inside the Qt Creator user resource
directory (**Open Agents Folder...** opens it). Press **Reload** after editing.
2. **The ACP registry**, downloaded from
`https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json` when you press
**Refresh from Registry** and cached on disk. There is no background polling: the
list only changes when you ask for it.
3. **A bundled snapshot**, so the list is never empty on a fresh install or offline.
If a download fails, the cached copy and the bundled snapshot stay in place.
## Finding the agent's executable
Qt Creator started from the Dock or a launcher does not inherit your shell's `PATH`, so
`npx` or `uvx` installed through Homebrew, nvm or uv is often invisible to it — the agent
then fails to start with `execve: No such file or directory`. **Extra PATH for launching
agents** on the Agents page lists directories that are both searched for the executable
and prepended to the agent's own `PATH`. On macOS it defaults to
`/opt/homebrew/bin:/usr/local/bin`. An `env` entry in the agent definition still wins over
it.
## Credentials and other environment variables
Some agents authenticate through an environment variable rather than the ACP handshake —
the Claude adapter, for instance, declares no `authMethods` at all and reads
`CLAUDE_CODE_OAUTH_TOKEN`. Since a Qt Creator started from the dock inherits no shell
environment, that variable never reaches the agent and it fails with an expired-session
error.
**Forward these variables to agents** on the Agents page takes variable *names*, not
values, and defaults to `CLAUDE_CODE_OAUTH_TOKEN`. For each name QodeAssist uses the value
from its own environment when it has one — which covers Windows, and any platform when Qt
Creator was launched from a terminal. On macOS and Linux the remaining names are read once
per session from a login shell (`$SHELL -l -i -c env`), so a token exported in your shell
profile works without being copied anywhere. Nothing is stored in the settings but the
names.
An `env` entry in the agent definition still wins over a forwarded variable.
## Distributions
An entry describes how the agent is started:
- `npx` — launched as `npx -y <package> <args>`. Requires Node.js on `PATH`.
- `uvx` — launched as `uvx <package> <args>`. Requires uv on `PATH`.
- `command` — launched directly. This is the QodeAssist extension used by your own
JSON files.
- `binary` — a downloadable platform archive. QodeAssist does not download binaries,
so these agents are listed but cannot be started. Install the agent yourself and add
a `command` entry for it.
## Defining your own agent
Create a `.json` file in the agents folder. A file holds either a single agent object
or a registry-shaped `{"agents": [...]}` document.
```json
{
"id": "my-agent",
"name": "My Agent",
"version": "1.0.0",
"description": "Locally installed agent",
"distribution": {
"command": {
"cmd": "/usr/local/bin/my-agent",
"args": ["acp"],
"env": { "MY_AGENT_LOG": "debug" }
}
}
}
```
Reusing an `id` from the registry overrides that entry — which is how you make a
`binary` agent launchable after installing it manually:
```json
{
"id": "cursor",
"name": "Cursor",
"distribution": {
"command": { "cmd": "/usr/local/bin/cursor-agent", "args": ["acp"] }
}
}
```
Agent definitions hold no secrets. Agents that need credentials authenticate through
the ACP handshake.
## Testing an agent
Select an agent and press **Test**. QodeAssist starts the process, runs the ACP
`initialize` handshake and reports the agent's name, version, protocol version,
whether it supports session persistence (`loadSession`), its prompt and MCP
capabilities, and its authentication methods. On failure it shows the error together
with the agent's own output.
## Long conversations and reopened sessions
When an agent conversation grows long, the **Hand over** button in the chat bottom
bar summarizes the transcript with your Chat Assistant configuration and continues in
a fresh agent session seeded with that summary — see
[chat-summarization.md](chat-summarization.md) for details. The same handover is
offered on the read-only banner when a saved agent session can no longer be resumed.

174
docs/agent-roles.md
View File

@@ -1,174 +0,0 @@
# Agent Roles
Agent Roles allow you to define different AI personas with specialized system prompts for various tasks. Switch between roles instantly in the chat interface to adapt the AI's behavior to your current needs.
## Overview
Agent Roles are reusable system prompt configurations that modify how the AI assistant responds. Instead of manually changing system prompts, you can create roles like "Developer", "Code Reviewer", or "Documentation Writer" and switch between them with a single click.
**Key Features:**
- **Quick Switching**: Change roles from the chat toolbar dropdown
- **Custom Prompts**: Each role has its own specialized system prompt
- **Built-in Roles**: Pre-configured Developer and Code Reviewer roles
- **Persistent**: Roles are saved locally and loaded on startup
- **Extensible**: Create unlimited custom roles for different tasks
## Default Roles
QodeAssist comes with three built-in roles:
### Developer
Experienced Qt/C++ developer with a structured workflow: analyze the problem, propose a solution, wait for approval, then implement. Best for implementation tasks where you want thoughtful, minimal code changes.
### Code Reviewer
Expert C++/QML code reviewer specializing in C++20 and Qt6. Checks for bugs, memory leaks, thread safety, Qt patterns, and production readiness. Provides direct, specific feedback with code examples.
### Researcher
Research-oriented developer who investigates problems and explores solutions. Analyzes problems, presents multiple approaches with trade-offs, and recommends the best option. Does not write implementation code — focuses on helping you make informed decisions.
## Using Agent Roles
### Switching Roles in Chat
1. Open the Chat Assistant (side panel, bottom panel, or popup window)
2. Locate the **Role selector** dropdown in the top toolbar (next to the configuration selector)
3. Select a role from the dropdown
4. The AI will now use the selected role's system prompt
**Note**: Selecting "No Role" uses only the base system prompt without role specialization.
### Viewing Active Role
Click the **Context** button (📋) in the chat toolbar to view:
- Base system prompt
- Current agent role and its system prompt
- Active project rules
## Managing Agent Roles
### Opening the Role Manager
Navigate to: `Qt Creator → Preferences → QodeAssist → Chat Assistant`
Scroll down to the **Agent Roles** section where you can manage all your roles.
### Creating a New Role
1. Click **Add...** button
2. Fill in the role details:
- **Name**: Display name shown in the dropdown (e.g., "Documentation Writer")
- **ID**: Unique identifier for the role file (e.g., "doc_writer")
- **Description**: Brief explanation of the role's purpose
- **System Prompt**: The specialized instructions for this role
3. Click **OK** to save
### Editing a Role
1. Select a role from the list
2. Click **Edit...** or double-click the role
3. Modify the fields as needed
4. Click **OK** to save changes
**Note**: Built-in roles cannot be edited directly. Duplicate them to create a modifiable copy.
### Duplicating a Role
1. Select a role to duplicate
2. Click **Duplicate...**
3. Modify the copy as needed
4. Click **OK** to save as a new role
### Deleting a Role
1. Select a custom role (built-in roles cannot be deleted)
2. Click **Delete**
3. Confirm deletion
## Creating Effective Roles
### System Prompt Tips
- **Be specific**: Clearly define the role's expertise and focus areas
- **Set expectations**: Describe the desired response format and style
- **Include guidelines**: Add specific rules or constraints for responses
- **Use structured prompts**: Break down complex roles into bullet points
## Storage Location
Agent roles are stored as JSON files in:
```
~/.config/QtProject/qtcreator/qodeassist/agent_roles/
```
**On different platforms:**
- **Linux**: `~/.config/QtProject/qtcreator/qodeassist/agent_roles/`
- **macOS**: `~/Library/Application Support/QtProject/Qt Creator/qodeassist/agent_roles/`
- **Windows**: `%APPDATA%\QtProject\qtcreator\qodeassist\agent_roles\`
### File Format
Each role is stored as a JSON file named `{id}.json`:
```json
{
"id": "doc_writer",
"name": "Documentation Writer",
"description": "Technical documentation and code comments",
"systemPrompt": "You are a technical documentation specialist...",
"isBuiltin": false
}
```
### Manual Editing
You can:
- Edit JSON files directly in any text editor
- Copy role files between machines
- Share roles with team members
- Version control your roles
- Click **Open Roles Folder...** to quickly access the directory
## How Roles Work
When a role is selected, the final system prompt is composed as:
```
┌─────────────────────────────────────────────────┐
│ Final System Prompt = Base Prompt + Role Prompt │
├─────────────────────────────────────────────────┤
│ 1. Base System Prompt (from Chat Settings) │
│ 2. Agent Role System Prompt │
│ 3. Project Rules (common/ + chat/) │
│ 4. Linked Files Context │
└─────────────────────────────────────────────────┘
```
This allows roles to augment rather than replace your base configuration.
## Best Practices
1. **Keep roles focused**: Each role should have a clear, specific purpose
2. **Use descriptive names**: Make it easy to identify roles at a glance
3. **Test your prompts**: Verify roles produce the expected behavior
4. **Iterate and improve**: Refine prompts based on AI responses
5. **Share with team**: Export and share useful roles with colleagues
## Troubleshooting
### Role Not Appearing in Dropdown
- Restart Qt Creator after adding roles manually
- Check JSON file format validity
- Verify file is in the correct directory
### Role Behavior Not as Expected
- Review the system prompt for clarity
- Check if base system prompt conflicts with role prompt
- Try a more specific or detailed prompt
## Related Documentation
- [Project Rules](project-rules.md) - Project-specific AI behavior customization
- [Chat Assistant Features](../README.md#chat-assistant) - Overview of chat functionality
- [File Context](file-context.md) - Attaching files to chat context

28
docs/chat-summarization.md
View File

@@ -11,7 +11,7 @@ When conversations grow long, they consume more context tokens with each message
- Important context for continuing the conversation
**Key Features:**
- **One-click compression**: Summarize directly from the chat toolbar
- **One-click compression**: Summarize directly from the chat bottom bar
- **Preserves original**: Creates a new chat file, keeping the original intact
- **Smart summaries**: AI extracts the most relevant information
- **Markdown formatted**: Summaries are well-structured and readable
@@ -21,10 +21,23 @@ When conversations grow long, they consume more context tokens with each message
### Compressing a Chat
1. Open any chat with conversation history
2. Click the **Compress** button (📦) in the chat top bar
2. Click the **Compress** button (📦) in the chat bottom bar
3. Wait for the AI to generate the summary
4. A new chat opens with the compressed summary
### Agent Sessions: Hand Over
In a chat bound to an ACP agent the same button reads **Hand over**. Instead of
writing a compressed chat file, it summarizes the transcript using your configured
Chat Assistant provider (the same LLM that powers compression) and starts a fresh
agent session with the summary as its opening context. The transcript in the chat
stays intact; only the agent-side session is replaced.
The button is disabled with an explanatory tooltip when the Chat Assistant
configuration is incomplete (provider, model, template, or URL missing), because the
summary is generated by that configuration. Auto-compression never triggers for agent
sessions — the agent manages its own context window.
### What Gets Preserved
The summarization process:
@@ -94,9 +107,12 @@ No additional configuration is required.
## Troubleshooting
### Compression Button Not Visible
- Ensure you have an active chat with messages
- Check that the chat top bar is visible
### Compression Button Disabled
- Hover the button: the tooltip explains why (for example, the Chat Assistant
configuration is unassigned, or an agent chat has nothing to summarize yet)
- Assign the chat feature in Preferences → QodeAssist if the tooltip says so
- While a compression or summary is running, the button is replaced by a progress
indicator with a Cancel action in the bottom bar
### Compression Fails
- Verify your Chat Assistant provider is configured correctly
@@ -110,6 +126,4 @@ No additional configuration is required.
## Related Documentation
- [Agent Roles](agent-roles.md) - Switch between AI personas
- [File Context](file-context.md) - Attach files to chat
- [Project Rules](project-rules.md) - Customize AI behavior

22
docs/file-context.md
View File

@@ -1,6 +1,6 @@
# File Context Feature
QodeAssist provides two powerful ways to include source code files in your chat conversations: Attachments and Linked Files. Each serves a distinct purpose and helps provide better context for the AI assistant.
QodeAssist lets you include source code files in your chat conversations as attachments.
## Attached Files
@@ -14,20 +14,8 @@ Attachments are designed for one-time code analysis and specific queries:
- Quick implementation questions
- Files can be attached using the paperclip icon in the chat interface
- Multiple files can be attached to a single message
- Files can also be added by dragging them onto the chat panel or with `@` mentions
## Linked Files
Linked files provide persistent context throughout the conversation:
- Files remain accessible for the entire chat session
- Content is included in every message exchange
- Files are automatically refreshed - always using latest content from disk
- Perfect for:
- Long-term refactoring discussions
- Complex architectural changes
- Multi-file implementations
- Maintaining context across related questions
- Can be managed using the link icon in the chat interface
- Supports automatic syncing with open editor files (can be enabled in settings)
- Files can be added/removed at any time during the conversation
For persistent, conversation-long context, enable tools (or use an ACP agent): the
model reads the files it needs from the project itself, always seeing the latest
content from disk.

35
docs/project-rules.md
View File

@@ -1,35 +0,0 @@
# Project Rules Configuration
QodeAssist supports project-specific rules to customize AI behavior for your codebase. Create a `.qodeassist/rules/` directory in your project root.
## Quick Start
```bash
mkdir -p .qodeassist/rules/{common,completion,chat,quickrefactor}
```
## Directory Structure
```
.qodeassist/
└── rules/
├── common/ # Applied to all contexts
├── completion/ # Code completion only
├── chat/ # Chat assistant only
└── quickrefactor/ # Quick refactor only
```
All `.md` files in each directory are automatically loaded and added to the system prompt.
## Example
Create `.qodeassist/rules/common/general.md`:
```markdown
# Project Guidelines
- Use snake_case for private members
- Prefix interfaces with 'I'
- Always document public APIs
- Prefer Qt containers over STL
```

2
docs/quick-refactoring.md
View File

@@ -206,7 +206,6 @@ The LLM receives:
- **Cursor Position**: Marked with `<cursor>` tag
- **Selection Markers**: `<selection_start>` and `<selection_end>` tags
- **Your Instructions**: Built-in, custom, or typed
- **Project Rules**: If configured (see [Project Rules](project-rules.md))
### Context Configuration
@@ -270,7 +269,6 @@ Fully local setup for offline or secure environments.
## Related Documentation
- [Project Rules](project-rules.md) - Project-specific AI behavior customization
- [File Context](file-context.md) - Attaching files to chat context
- [Ignoring Files](ignoring-files.md) - Exclude files from AI context
- [Provider Configuration](../README.md#configuration) - Setting up LLM providers