TUI mode
Run qoderclicn in any project root to enter the default TUI (interactive) mode. You can either chat with the CLI in natural language or use slash commands to trigger specific features.
Input modes
The TUI provides several input modes:
| Command | Description |
|---|---|
> | Chat mode (default). Enter any text to converse with the CLI. |
! | Bash mode. In chat mode, enter ! to run shell commands directly. |
/ | Slash mode. In chat mode, enter / to open and run built-in commands. |
\⏎ | Press Enter to start multiline input. |
Built-in tools
Qoder CN CLI ships with built-in tools such as Grep, Read, Write, and Bash for file/directory operations and shell command execution.
Slash commands
The following built-in slash commands provide quick access to features and settings:
| Command | Description |
|---|---|
/login | Log in to your Qoder CN account. |
/help | Show TUI help. |
/init | Initialize or update the AGENTS.md memory file in the project. |
/memory | Open the memory overview to manage user-level, project-level, local memory, and auto-memory entries. |
/quest | Run a spec-based delegated task. |
/review | Review local code changes. |
/resume | View and resume sessions. |
/clear | Clear the history context of the current session. |
/compact | Summarize the history context of the current session. |
/usage | Show the current credit usage. |
/status | View CLI status, including version, model, account, API connectivity, and tool status. |
/config | View the Qoder CN CLI system configuration. |
/effort | Adjust the reasoning depth of the current model and related model parameters. |
/agents | Subagent command: view, create, and manage subagents. |
/tasks | View background tasks that are currently running. |
/release-notes | Show the Qoder CN CLI release notes. |
/vim | Open an external editor to edit input. |
/feedback | Send feedback about Qoder CN CLI. |
/quit | Exit the TUI. |
/logout | Log out of your Qoder CN account. |
Advanced startup options
When launching the CLI, use the following options to control its behavior:
| Option | Description | Example |
|---|---|---|
-w | Specify the workspace directory. | qoderclicn -w /Users/demo/projects/nacos |
-c | Continue the last session. | qoderclicn -c |
-r | Resume a specific session. | qoderclicn -r *******-c09a-40a9-82a7-a565413fa39 |
--allowed-tools | Allow only the specified tools. | qoderclicn --allowed-tools=Read,Write |
--disallowed-tools | Disallow the specified tools. | qoderclicn --disallowed-tools=Read,Write |
--max-turns | Set the maximum number of conversation turns. | qoderclicn --max-turns=10 |
--yolo | Skip permission checks. | qoderclicn --yolo |
Print mode
Print mode is a non-interactive mode. Run qoderclicn --print to enter this mode. The output is printed in the format specified by --output-format.
Parameters
The following global parameters can be used with any command:
| Parameter | Description | Example |
|---|---|---|
-p | Run the agent non-interactively. | qoderclicn -q -p hi |
--output-format | Output format: text, json, or stream-json. | qoderclicn --output-format=json |
-w | Specify the workspace directory. | qoderclicn -w /Users/qoder_user/projects/qoder_demo |
-c | Continue the last session. | qoderclicn -c |
-r | Resume a specific session. | qoderclicn -r ********-c09a-40a9-82a7-a565413fa393 |
--allowed-tools | Allow only the specified tools. | qoderclicn --allowed-tools=Read,Write |
--disallowed-tools | Disallow the specified tools. | qoderclicn --disallowed-tools=Read,Write |
--max-turns | Set the maximum number of conversation turns. | qoderclicn --max-turns=10 |
--yolo | Skip permission checks. | qoderclicn --yolo |
MCP services
Qoder CN CLI can connect to Model Context Protocol (MCP) services to use external tools and data sources. Once a service is added, its tools are available to the agent in both interactive and non-interactive sessions.
Quick start
Use qoderclicn mcp add to add a stdio MCP service. The command following -- is the service process that Qoder CN CLI needs to launch.
/mcp reload to rediscover MCP services and tools; new sessions perform discovery automatically at startup.
Service types
Use -t to choose the MCP transport type.
| Type | Use case |
|---|---|
stdio | MCP service runs as a local command. |
sse | MCP service is exposed through a Server-Sent Events endpoint. |
http | MCP service is exposed through an HTTP endpoint. |
ws | MCP service is exposed through a WebSocket endpoint. |
Scope
Use -s to choose where the MCP service configuration is saved.
| Scope | Use case |
|---|---|
user | You want the service to be available across all projects for the current account. |
local | You want the service to be available only for the current project on this machine. This is the default scope. |
project | You want the service configuration to be shared with the project. |
Manage services
List configured services:
Recommended services
Common MCP services include:
MCP permissions
MCP tools still go through the Qoder CN CLI permission system. In default mode, MCP tool calls typically require confirmation. You can approve a specific tool, approve all tools under a given MCP service, or configure rules in settings. MCP tool names typically use the following format:
Troubleshooting
If MCP tools are unavailable:
- Run
qoderclicn mcp listto confirm that the service is configured. - If Qoder CN CLI is already running, execute
/mcp reloadafter adding or modifying a service. - Verify that the command following
--can run correctly in a terminal. - For
npx-based services, confirm that Node.js and network access are available. - If a service is connected but tool calls are blocked, check the permission prompts.
Permissions
Qoder CN CLI provides fine-grained permission control over tool execution, covering file reads and writes, Bash commands, web fetching, MCP tools, subagents, and other built-in tools.
Permission modes
Permission modes determine how Qoder CN CLI handles tool calls. Each mode is positioned differently along the two dimensions of "automation level" and "safety leniency".
| Mode | Use case | Behavior |
|---|---|---|
default | Regular interactive use. | Safe reads and internal actions run automatically; sensitive operations require confirmation. |
accept_edits | Everyday coding tasks. | Safe file edits within the working directory are auto-approved; shell commands, external actions, and sensitive paths still go through normal checks. |
auto | Automated runs and goal execution. | No prompts. Safe reads and edits within the workspace are auto-approved; risky actions are denied or handed off to an AI classifier. |
bypass_permissions (YOLO) | For trusted local experiments only. | Skips all approval prompts. All tool calls are automatically allowed. |
dont_ask | Headless workflows that must not prompt. | Never asks. Any action that would normally require confirmation is denied. |
Plan and Goal modes
Plan is an independent work state (not a permission policy) that coexists with any of the permission modes above. Toggle it with the /plan command. Once entered, Qoder CN CLI performs read-only code exploration and outputs a plan; writes are restricted to plan files.
Goal is an autonomous execution state. Enter it with /goal set <goal> — this automatically switches to auto mode and locks the Shift+Tab toggle. Use /goal clear or /goal pause to exit.
In an interactive session, press Shift+Tab to cycle through all permission modes; press Ctrl+Y to jump directly to YOLO mode.
Startup parameters
Use --permission-mode to select the default behavior for the current session:
accept_edits / acceptEdits, bypass_permissions / bypassPermissions / yolo, and dont_ask / dontAsk.
How permissions are decided
Qoder CN CLI performs a permission check before each tool call. There are only three possible results: allow (execute immediately), ask (external confirmation required), and deny (execution blocked).
Decision order:
- Check
denyrules first — if matched, deny. - The tool's own safety checks (such as dangerous command detection and sensitive path detection).
askrules — if matched, mark as requiring confirmation.- Tool-level
allowrules and any automatic allow behavior implied by the mode. - If the final result is still
ask, the runtime environment decides how to consume it.
| Runtime | Fate of ask | Description |
|---|---|---|
| TUI (interactive terminal) | Confirmation prompt. | The user chooses allow/deny in the terminal. |
Headless (-p/--prompt) | Auto-denied. | Nobody is available to interact; ask becomes deny. |
| SDK (stdio protocol) | Sends a canUseTool callback to the host. | The host program decides allow/deny. |
| ACP (IDE integration) | Sends a requestPermission RPC to the IDE. | The IDE prompts or auto-decides. |
Configuration sources and precedence
Rules are merged from multiple sources across 8 layers, from lowest to highest precedence:
| Layer | Source | Description |
|---|---|---|
| 1 | userSettings | ~/.qoder-cn/settings.json (user-global). |
| 2 | projectSettings | /.qoder/settings.json (project-level, shared with the team). |
| 3 | localSettings | /.qoder/settings.local.json (per-machine, personal; added to .gitignore). |
| 4 | flagSettings | File specified via the --settings CLI parameter. |
| 5 | cliArg | --allowed-tools / --disallowed-tools command-line parameters. |
| 6 | command | In-session commands such as /allow and /deny. |
| 7 | session | Temporary rules created at runtime ("Allow for this session" in a prompt). |
allowManagedPermissionRulesOnly, only policy-managed rules are used.
Mode configuration
Set the default mode — configure general.defaultPermissionMode in ~/.qoder/settings.json:
Permission rule configuration
Qoder CN CLI enforces permissions through three core strategies: Allow, Deny, and Ask. The relevant configuration files, in increasing order of precedence, are:
allow, ask, and deny:
| Form | Meaning |
|---|---|
ToolName | Applies to the entire tool. |
ToolName(content) | Applies to a specific path, command, agent type, or other tool-specific content. |
* | Matches all tools. |
Read, Edit, Write, Bash, Grep, Glob, WebFetch, WebSearch, Agent, along with MCP tool names such as mcp__github__create_issue.
Command-line override:
Trusted directories
Qoder CN CLI treats the current working directory (CWD) at startup as the primary trusted directory. Inside a trusted directory, file reads are allowed by default; file writes can be auto-approved in accept_edits and auto modes; and non-default permission modes (auto, bypass, and so on) can take effect.
If the current directory is not trusted, Qoder CN CLI is forced back to default mode. Add additional trusted working directories via --add-dir, the /add-dir command, or permissions.additionalDirectories:
.git, .vscode, .idea, .husky, most .qoder configuration files, shell startup files such as .bashrc/.zshrc, Git configuration, .mcp.json, and .ripgreprc. In regular interactive mode, these paths require explicit approval; in auto mode, they are denied.
File access rules
Read and Edit Read rules apply to all file-reading tools (such as Grep and Glob); edit rules apply to Edit, Write, and NotebookEdit. File rules use gitignore-style matching.
| Pattern | Meaning |
|---|---|
/src/** | Path relative to the rule source root. In project/local settings this is relative to the project root; in user settings it is relative to the home directory. |
~/Documents/** | Path relative to the home directory. |
//tmp/data/** | An absolute path starting from the system /; requires a double slash. |
*.secret | A filename pattern without a root; matches at any location. |
Bash rules
Bash(...) rules can match exact commands, command prefixes, or wildcard patterns:
Bash(npm run build)matchesnpm run buildexactly.Bash(npm run test:*)matches any command starting withnpm run test.Bash(git log *)uses glob-style wildcards.
deny and ask rules pass through common wrappers and environment-variable prefixes; prefix and wildcard allow rules do not silently approve compound commands; and dangerous commands (such as destructive deletion or force push) may force confirmation even when a broad allow rule exists. In auto mode, dangerous shell commands are denied.
Web and MCP rules
WebFetch restricts the domains that the web fetch tool can access. For example, WebFetch(domain:example.com) limits fetches to example.com.
MCP MCP tools use the fully qualified name mcp__<server>__<tool>; you can use mcp__github__* to match all tools of a given server, or mcp__* to match all MCP tools. To restrict the run to specific MCP servers, use --allowed-mcp-server-names:
Hooks and permissions
The Qoder CN CLI hook system has two injection points in the permission decision chain: PreToolUse (before tool execution) and PermissionRequest (after the permission pipeline produces ask, before the prompt is shown). Hook permission decisions take precedence over permission modes — even in bypass_permissions mode, a deny returned by a PreToolUse hook still blocks execution. See Hooks for details.
Worktree
Use --worktree [name] to start a Qoder CN CLI session in an isolated Git worktree. This is suitable for working on multiple tasks in parallel within the same repository, avoiding conflicts caused by multiple sessions sharing the same working directory.
Start in a worktree
Remove a worktree manually
To remove a worktree manually, run:
Memory
Qoder CN CLI reconstructs its context for each session. Knowledge that needs to be retained across sessions comes from two main types of memory:
AGENTS.mdfiles: persistent instructions maintained by you or your team; suitable for development conventions, project structure, common commands, and collaboration agreements.- Auto-memory: Markdown memory that Qoder CN CLI saves locally when enabled; suitable for recording preferences, feedback, project background, and external references that remain useful in later sessions.
Common AGENTS.md locations
| Location | Purpose | Suitable for commit |
|---|---|---|
~/.qoder-cn/AGENTS.md | General cross-project preferences and habits for the current user. | No |
${project}/AGENTS.md | Team-shared project rules, architecture notes, and common commands. | Yes |
${project}/AGENTS.local.md | Project-specific notes for the current machine, such as local service endpoints or personal test data. | No |
${project}/.qoder/rules/*.md | Project rules split by topic or file scope. | Yes |
context.fileName to a single file name or an array of file names. The default value is AGENTS.md.
Loading logic
When Qoder CN CLI starts up or refreshes memory, project memory is looked up upward, checking the project rules directory at each level:
- User-level memory: loads
AGENTS.mdfrom the user configuration directory. - Project and local project memory: within a trusted workspace, searches from the current workspace directory upward for
AGENTS.md,AGENTS.local.md, and.qoder/rules/**/*.md, stopping by default at the directory containing.git. - Rules without a
pathsfrontmatter are loaded together with project memory; rules with apathsfrontmatter are loaded on demand only after Qoder CN CLI accesses a matching file. - Subdirectory memory: not preloaded at startup. Only after Qoder CN CLI successfully reads a file in a subdirectory does it walk up from that file's directory and load any memory files that had not been loaded before.
Rules
Rules are instruction files placed under the rules/ directory and split by topic, used as an alternative to a single, bloated AGENTS.md. Rules have two scopes:
| Scope | Location | Applies to | Suitable for commit |
|---|---|---|---|
| Project | ${project}/.qoder/rules/**/*.md | The project containing the file; shared with the team. | Yes |
| User | ~/.qoder-cn/rules/**/*.md | Every project you open; personal to this machine. | No |
paths frontmatter of a rule determines when it is loaded: without paths, it always applies; with paths, it applies according to the path. Example:
Management and auto-memory
In the TUI, enter /memory to open the memory overview and manage user-level, project-level, and local memory files; running /init generates AGENTS.md in the project directory.
Auto-memory only runs in interactive sessions and is enabled through an environment variable:
~/.qoder-cn/projects/<project>/memory/; when the user level is enabled, ~/.qoder-cn/memory/ is also used. Once enabled, you can open the auto-memory folder from the /memory panel, or enter /memory manage to manage the auto-saved memory files.
Importing other files
AGENTS.md can pull in other files with @path/to/file. Relative paths are resolved against the directory of the current AGENTS.md. Relative paths, absolute paths, and ~/ paths are supported; @... occurrences inside inline code or code blocks are not recognized as imports.
Subagents
A subagent is an agent in Qoder CN CLI specialized for a particular type of task. Each subagent has its own conversation context, tool set, model configuration, permission mode, and runtime limits, making it suitable for delegating focused work such as code exploration, solution design, interface review, and test coverage. In the TUI, run /agents to open the configuration panel to view, create, and manage subagents. For full capabilities, source precedence, configuration fields, and usage, see Subagents.
Commands
Commands (slash commands) are shortcuts in Qoder CN CLI for triggering specific tasks, invoked with a slash (/) prefix. In TUI mode, entering / shows the list of available commands to select and run; headless mode also supports running commands that submit prompts.
Command types
| Type | Description | Supported modes | Extensibility |
|---|---|---|---|
| TUI type | Provides an interactive interface (such as pop-up dialogs and list selection). | TUI | System built-in; not user-extensible. |
| Prompt type | Submits a predefined prompt to the conversation, guiding the CLI to complete a specific task. | TUI + Headless | Supports user-defined extensions. |
Built-in commands
Common built-in commands provided by Qoder CN CLI:
Command | Type | Purpose |
| TUI | View and manage the subagent list; supports creating and editing subagent configurations. |
| TUI | View and manage background tasks. |
| TUI | Open the dynamic workflow task panel. |
| TUI | Clear the current conversation and start a new one. |
| TUI | View and manage custom commands; supports creating and editing command configurations. |
| Prompt | Compact the conversation history; can specify a focus area. |
| TUI | Configuration management; view or modify Qoder CN CLI configuration items. |
| TUI | Export the current session to a file. |
| TUI | Submit feedback or report an issue. |
| TUI | Show help information. |
| TUI | Initialize the project by analyzing its structure and generating the |
| TUI | Log in to your Qoder CN CLI account. |
| TUI | Log out of your Qoder CN CLI account. |
| TUI | MCP service management. |
| TUI | Open the memory overview; when auto-memory is enabled, open the auto-memory folder, or use |
| TUI | View and manage model-level settings. |
| TUI | Set the reasoning depth of the current model; without a level, opens the model parameter panel. |
| TUI | Set the context window of the current model; without arguments, opens the model parameter panel. |
| TUI | Toggle fast mode for the current model; without arguments, opens the model parameter panel. |
| Prompt | Intelligent workflow orchestrator; multiple agents work together to help the user complete feature development. |
| TUI | Exit Qoder CN CLI. |
| TUI | View version release notes. |
| TUI | Resume a previous session or conversation history; supports Tab to page through sessions. |
| Prompt | Run a code review to check code quality and conformance. |
| TUI | GitHub integration configuration for setting up GitHub-related features. |
| TUI | Manage Skill commands for the current workspace. |
| TUI | View the current session status and system information. |
| TUI | Upgrade your subscription plan. |
| TUI | View usage statistics, including token consumption. |
| TUI | Enable or configure Vim mode for a Vim-style editing experience. |
Create custom commands
Qoder CN CLI supports creating Prompt-type custom commands whose name, description, and system prompt are defined through a configuration file. The configuration file is in Markdown format and contains frontmatter metadata and a system prompt:
name (required) — the unique name of the command, used for /command-name invocation; description (required) — the functional description of the command, supporting multi-line text (using YAML syntax).
Naming conventions: use lowercase letters and hyphens (for example, git-commit); avoid spaces and special characters; it is recommended that the file name match the name field; commands in subdirectories use : as a namespace separator (for example, commands/git/commit.md is registered as /git:commit); if a SKILL.md exists in the same directory, that directory is registered as a single command, and any sibling .md files are ignored.
Storage locations and precedence
Command configuration files can be stored in project-level or user-level directories:
| Level | Path | Applies to | Commit to repository |
|---|---|---|---|
| Project | .qoder/commands/<command_name>.md | Current project only. | Recommended (team-shared). |
| User | ~/.qoder-cn/commands/<command_name>.md | All projects. | Not committed (personal configuration). |
/commands to reload after adding or modifying a command configuration file.
Example
Define a command as follows and save it to ~/.qoder-cn/commands/quest.md.
/quest to trigger the command; during execution, the two subagents are invoked in order as specified by the prompt.