Quick Start Guide

1. About this book

AVL Code is an AI desktop assistant for coding and security analysis. Its documentation comes in three books with a clear division of labour:

Suggested lookup path:

1. First time → read this book end to end, doing as you read.
2. Going deeper on a feature → the matching User Manual chapter.
3. Just looking up one setting / command / parameter → go straight to the Reference Manual.

Ref boxes in this book look like this:

[!ref] Example: the full story on this topic is in the User Manual, "Workspaces".

When you hit a ref box, it means this book covers the topic only as far as you need to get going; the deep-dive lives in the chapter it points to. Tutorials appear only in this book, deep-dives only in the User Manual, cheat sheets only in the Reference Manual — the three books do not repeat each other.

2. Install and sign in (about 10 minutes)

2.1 Download and run (install-free)

AVL Code is install-free — download and run (no installer wizard). From the official download page www.avlcode.cn/#download, pick the build for your platform and run it directly (the beta uses the alpha channel — links always point to the latest build):

[!warning] On macOS, be sure to drag the app into Applications before running — otherwise, when run straight from Downloads or the Desktop, "check for updates" is locked by the system's App Translocation mechanism.

2.2 System requirements

2.3 First launch

After launch you see three main areas:

• Left sidebar: workspace list + sign-in / account + Settings entry.
• Center session area: session tabs + message stream + input box.
• Right side: plan / todo / approval status blocks, appearing on demand.

On first launch we recommend clicking the Sign In button in the lower left to bind your account (next section). You can also use the app without signing in, but you then need to enter an API key manually under Settings → Models.

2.4 Sign in (one-click setup)

Signing in automatically provisions a shared billing quota for this machine, so no manual API key configuration is needed. Three ways to sign in:

• SMS verification code (default and fastest): enter a phone number → receive an SMS code → signed in. If the account doesn't exist it is auto-registered — no separate registration flow.
• Username + password: Settings → Account → Password tab.
• SSO single sign-on: Settings → Account → SSO Sign In opens your browser to authenticate, then bounces back.

After signing in:

1. A shared quota is provisioned for the account automatically.
2. The model list refreshes asynchronously so you can start chatting immediately.
3. Settings → Account starts showing 24-hour / 7-day / 30-day usage plus points balance.

[!note] Want to connect directly to a Claude endpoint, an OpenAI-compatible proxy or a self-hosted LLM service: Settings → Providers → + Add, enter the endpoint URL + API key. Once enabled, AVL Code uses your own key first and falls back to the shared quota as a backstop.

[!ref] The three provider protocols (AVL Delta / OpenAI / Anthropic), custom request headers and parameters are covered in the User Manual, "Models and parameters"; usage, redemption codes and billing in the User Manual, "Account, usage and billing".

3. Your first workspace and first conversation (about 10 minutes)

3.1 Create your first workspace

A workspace is AVL Code's smallest unit of execution. Each workspace binds one local directory plus a set of configuration.

1. Click "+ New Workspace" in the sidebar.
2. Pick a local path (e.g. ~/projects/my-app or ~/samples/2026-04-malware).
3. Give the workspace a short name.

After creation the session history, skill extensions and companion-messaging bindings are all kept per-workspace and don't interfere with each other.

[!ref] Directory layout, SSH remote workspaces, project instructions (AGENTS.md) and session-level path attachments are covered in the User Manual, "Workspaces" and "Sessions".

3.2 Sessions

A session is one continuous conversation context. AVL Code persistently appends every message to disk; power loss, shutdown and restart never lose data.

• New session: right-click the session tab bar → New, or {{kbd:Cmd+N}}.
• Rename / archive: right-click menu on the tab.
• History compaction: when the context nears its limit, history is automatically compacted into a summary; original messages are preserved and can be expanded.

3.3 Your first conversation

Describe what you want the AI to do in one sentence in the input box and press Enter. While it runs you'll see:

• The send button becomes a "Stop" button — pressing it terminates the main assistant and all spawned sub-tasks together.
• If you think of something to add mid-run, just press Enter to queue it — it merges in after the current turn ends naturally, without interrupting it.
• Every tool call appears as a collapsible card in the message stream: tool name + parameter summary, elapsed time, result (success / failure / truncated).

[!tip] When your opening message is short or vague, the AI first restates its intent (goal + plan) for your confirmation before acting; say it clearly enough and it just gets going. On by default and can be turned off — see the User Manual, "Sessions".

4. Making the AI actually work: five modes and tool approval (about 15 minutes)

4.1 The five work modes

Work modes are the core of AVL Code's assistant system. Each workspace can bind a different assistant persona to each of the five modes.

[!note] The difference between plan and assess: plan is strictly read-only and can't even run a command; assess doesn't write project code, but it can run tests, lint and SAST and generate an SBOM, so acceptance rests on real evidence.

4.2 Switching modes

A row of five round buttons below the input box switches modes with one click. The switch automatically loads the persona bound to that mode and applies the mode's tool-enable set.

[!ref] Each assistant's name, personality and core prompt are customisable, and there's a "hand of fate" mode for one-off persona assignment — see the User Manual, "Assistant personas".

4.3 Three-state tool permission

AVL Code applies fine-grained control to every tool call. Each tool can be set to:

• Allow: pass through.
• Ask: pop an approval dialog before every call.
• Deny: reject outright.

This is configured via the gear next to the mode slider in the input area (agent manager) → "Configure tools", per work mode. The three states actually constrain the run: "Deny" takes effect on the main agent and sub-agents alike, and "Ask" pauses the call until you approve.

4.4 Approve before use

When a tool marked "Ask" is about to run:

1. The desktop pops an approval dialog showing the tool name, parameters and impact.
2. You choose:
   • Allow (once)
   • Always allow (added to the allow list)
   • Deny

[!warning] The approval dialog has a 30-second countdown; no response by the end counts as Deny.

[!tip] With a WeChat channel bound, approval cards mirror to your phone and you can approve remotely — see Task Five in Chapter 5.

[!ref] Allow-list matching rules, multi-device approval and the approval audit trail are covered in the User Manual, "Tool permissions and approval"; the policy field cheat-sheet is in the Reference Manual, "Tool permission policy".

5. Five hands-on tasks

The five tasks are independent of each other; each follows the same shape — prerequisites → steps → expected result. Pick whichever you need.

5.1 Task one (coding): add unit tests to a function

Prerequisites: signed in; a workspace bound to a code project (Chapter 3).

Steps:

1. Switch to plan mode — every write operation is rejected; the AI reads, looks and thinks only.
2. State the requirement in the input box (swap in a path and function that actually exist in your project), e.g.: "Look at src/utils/format.ts and propose a few unit tests for formatDate. Plan first."
3. Review the plan: the assistant replies with a plan + todo list; on the plan float you can accept / edit / reject.
4. After accepting, click "Exit Plan, Enter Execute" — AVL Code switches to execute automatically, and the assistant actually invokes read-file / edit-file / shell tools to make the edits and run the tests.
5. When done, switch to assess and have the assistant read the test results and logs and draw conclusions with improvement suggestions — it won't change your code any more, but it can actually run tests to back its conclusions.

Expected result: at wrap-up AVL Code flags the task with a "Passed" or "Failed" banner.

5.2 Task two (coding): install a skill and trigger it with a / command

A skill is a small package of prompt template + metadata that gives the assistant "domain expert" capability; the skill system is compatible with the mainstream community format, so you can reuse the existing ecosystem directly.

Prerequisites: signed in.

Steps:

1. Settings → Plugins → Marketplace — pick a plugin. The pre-install confirmation dialog lays out source / command lines / capabilities / signature for review before you install.
2. After install, the plugin's skills and hooks are active by default in every workspace (can be disabled as needed).
3. Back in the input box, type / to open the command palette, or type /skill-name arg1 arg2 directly and send.

Expected result: the skill you trigger is rendered and injected into the next turn's context; the assistant can also invoke skills on its own, with results returning to the conversation stream as tool responses.

[!note] Skills come from three layers: global / workspace / plugin; the workspace version overrides the global one, which is handy when different projects need different flavours of the same skill.

[!tip] External MCP tool services (HTTP / SSE cloud services, or npx-style stdio local processes) are connected via the agent manager → "Configure tools" → add a service; a newly-connected service is visible to the assistant on the next turn — no need to restart the conversation.

[!ref] Skill pack structure, signing and debugging: User Manual, "The Skill system"; the plugin marketplace and the out-of-the-box plugin catalogue: User Manual, "Plugins and extensions"; OAuth login, credential encryption and the health board for external services: User Manual, "External tool services".

5.3 Task three (security analysis): drop a sample and run a first-pass triage

Prerequisites: signed in; a samples workspace (e.g. ~/samples/2026-04-malware); an executable to analyse.

Steps:

1. Click the "+" button at the bottom-left of the input box and pick the sample in the system file dialog — the file lands directly in the current workspace's samples/ subdirectory, and the area above the input box shows file name + progress bar.
2. In the conversation, send: "Run hash + entropy + ioc_extract on that PE and give me a first-pass verdict."
3. If one of the analysis tools involved is set to "Ask", allow it in the approval dialog.

Expected result: call cards for the read-only analysis tools (hash, entropy, IOC extraction) appear in the message stream, and the assistant replies with a first-pass verdict based on the tool output.

[!note] Samples default to a 300 MiB cap (adjustable in Settings → Data → Attachments / Samples); duplicate names get a timestamp suffix — never silently overwritten.

[!ref] The full security-analysis capability set (format parsing, disassembly, decompilation, rule matching, packet metadata, cloud threat intelligence and Sentinel scanning): User Manual, "Security-analysis tools"; the per-tool parameter cheat-sheet: Reference Manual, "Security-analysis tools".

5.4 Task four (security analysis): give a project a supply-chain check-up (SBOM)

Prerequisites: a project workspace containing a dependency manifest (e.g. package-lock.json / go.mod / requirements.txt).

Steps:

1. Ask the assistant to generate a software bill of materials for the project (sbom.generate) — 16 ecosystems and 22 manifest formats across npm / Go / Python / Maven / Rust and more are recognised automatically.
2. Have it go on to audit the dependencies for known vulnerabilities (sbom.audit) — checked against the OSV / CVE / KEV vulnerability databases, with conclusions ranked by CVSS severity.
3. (Optional) have it run reachability convergence (sbom.vex) — symbol-level reachability analysis converges away vulnerabilities that are "installed but never called".

Expected result: result files land in the workspace's .avlcode/ directory by default; vulnerabilities are sorted most-severe-first, and KEV (known-exploited) entries always stay on top.

[!ref] Ecosystem coverage, offline / air-gap usage and the CycloneDX / SPDX / OpenVEX output formats: User Manual, "Security-analysis tools".

5.5 Task five (everyday collaboration): bind WeChat and drive / approve from your phone

Prerequisites: desktop signed in with a target workspace; WeChat on your phone.

Steps:

1. Settings → Companion Messaging — scan the QR code with WeChat to log into the channel.
2. On the desktop, generate a 6-digit pairing code for the target workspace (valid for 10 minutes).
3. In a WeChat direct or group chat, send: /bind 123456.
4. Once bound, just send messages to drive the desktop assistant; when an approval comes up, the approval card is pushed into the chat — reply /approve <approval-id> (allow once) / /always <approval-id> (always allow) / /deny <approval-id> (deny).
5. On the phone, /s <short-id> resumes an unfinished desktop session; /stop / /resume pauses-and-terminates / resumes running tasks.

Expected result: desktop and WeChat sessions share state automatically, and the conversation survives restarts intact; approving in WeChat dismisses the desktop dialog in sync and the whole task continues on its own.

[!note] Long replies auto-chunk to stay under WeChat's per-message length limit; while processing, the assistant uses the "typing" indicator as its receipt instead of sending placeholder text.

[!ref] The full command table: Reference Manual, "Companion-messaging commands"; routing strategy, group collaboration and safety boundaries: User Manual, "Companion messaging".

6. Where to go next

With the first five chapters done, you have completed a first full loop — from install and sign-in through coding, security analysis and companion collaboration. When you want to go deeper, use this table:

Three everyday conveniences, one line each:

• Tray and auto-start: Settings → General can enable "minimise to system tray" (closing the window doesn't quit) and "start at login" (silent start into the tray on boot).
• Theme and appearance: three theme tiers — system / light / dark; the quick menu at the top right of the header gathers four sliders — theme, layout (sidebar / top tabs), density (Normal / Compact) and language (简 / 繁 / EN) — no need to open the Settings page.
• Upgrade / uninstall / troubleshooting: in-app upgrade lives in the tray menu → check for updates — packages are signature-verified, with auto-rollback on a failed verification; to uninstall, delete the app itself — a full wipe also requires removing the data directory; when something breaks, start from Settings → Data → Open log directory.

[!ref] Details in the User Manual chapters "System tray and auto-start", "Theme and appearance", "Upgrade, backup and sync", "Uninstall and data cleanup" and "Troubleshooting and FAQ".

Appendix: quick troubleshooting

This appendix covers only the problems that keep you from using AVL Code at all — it won't start, or you can't log in. For everything else, follow the pointers in the previous chapter to the User Manual.

• App won't start: check the logs first (Settings → Data → Open log directory); or reinstall and retry.
• Blank window after launch: usually the system's built-in webview component is too old — upgrade it per the Chapter 2 system requirements (Windows: WebView2; Linux: webkit2gtk).
• "Service not ready": wait a few seconds — a child process is still initialising; if it persists beyond 30 seconds, open Settings → Hooks → Error Drawer for the actual cause.
• No models after sign-in: Settings → Account → force refresh; or sign out and back in.
• Session suddenly unresponsive: click the Stop button to the right of the input box (it terminates all spawned tasks too), then send a new message.

[!ref] More troubleshooting (tool, security-analysis, companion-messaging and performance issues): User Manual, "Troubleshooting and FAQ".

License: AVL Code Proprietary Software License — Copyright © 2024–2026 Antiy. All Rights Reserved. Document version: 2026-08-03, matching app version v0.8.3-alpha.