English | 简体中文 | Documentation

Development Status

LiliaCode is still changing quickly. Core features are not fully complete, and the local database schema may change as new features land. Data may be cleared or migrated at any time, so do not rely on it as the only copy of important production work.

A desktop client for agent-assisted software engineering.

LiliaCode organizes Claude Code and Codex execution behind Lilia workflows, runtime commands, and recoverable local task state, helping developers manage project sessions, context, todos, and execution history.

LiliaCode is the software engineering workbench in the Lilia family. It does not simply wrap Claude Code or Codex in a chat window; instead, it adds a desktop-level organization layer for projects, tasks, sessions, permissions, and process state outside the agent execution layer.

It is built for developers who move engineering projects forward over time. Each conversation can be treated as a manageable task, while agent execution details and pending interactions are saved as local state. This provides the foundation for future task trees, automatic orchestration, and multi-agent collaboration.

Lilia is a family of toolchain applications for high-collaboration agent workflows. Its goal is to connect different agents, execution environments, and engineering workflows into one observable, schedulable, and recoverable local workbench.

LiliaCode focuses on software engineering. Other applications in the same family may expand into additional agent collaboration workflows while sharing the same ideas around project state, task-based sessions, plugin capabilities, and human-agent collaboration boundaries.

• Task-based sessions: manage conversations as tasks instead of only saving chat history.
• Local engineering state: record projects, sessions, todos, process details, and key interactions for easier recovery and continuation.
• Observable process: use a timeline to show agent reasoning, tool calls, command execution, file changes, and final responses.
• Non-interruptive interaction: move permission requests, plan confirmations, and agent questions into a pending area so they do not take over the input flow.
• Collaboration-ready structure: provide a shared shape for task trees, dependencies, orchestration, and helper agents.

LiliaCode still prioritizes its own recoverable task structure over upstream CLI or SDK history formats. Raw Claude / Codex history can be imported as a bridge into Lilia tasks, but the local task timeline remains the primary working model.

• Run Claude: make sure Node.js 18+ is available, then choose Claude on the Connection page and enter an Anthropic API key. If Base URL is empty, Lilia uses https://api.anthropic.com; you can also enter a local proxy or Anthropic-compatible endpoint.
• Run Codex: install Codex CLI with npm i -g @openai/codex, then make sure Lilia can detect codex app-server. Lilia requires Codex CLI 0.128.0+ for the app-server protocol it uses; by default it reuses the official account session from codex login.
• Codex API: to bill through an OpenAI API key, switch Codex to API mode on the Connection page and enter OPENAI_API_KEY. If Base URL is empty, Lilia uses https://api.openai.com/v1.
• Compatible APIs / local proxies: enter the service URL directly as Base URL. CC-Switch no longer has dedicated integration and is treated as a normal API source, for example http://127.0.0.1:15721.
• Fix failures: the Connection page maps missing Node, missing Codex CLI, old app-server support, missing Codex login, and missing API keys to concrete repair suggestions. After fixing an item, click Refresh check, then return to a conversation and send the first message.

The list below tracks the current real integration surface. Only capabilities that are usable as user-facing features are marked complete; partially integrated and not-yet-integrated items remain unchecked. Last checked: 2026-06-13.

• Permission modes: choose execution scope by risk level, including full access, ask-first, and read-only modes, and map them into Claude / Codex runtime parameters.
• Todo display: mirror Claude TodoWrite and Codex todo_list events to show the agent's current task list and progress.
• Process timeline: distinguish and display agent reasoning, commands, tool calls, file changes, plans, and final replies.
• Key node navigation: highlight important timeline nodes in the scrollbar and support quick jumps.
• Non-interruptive interaction mode: move permission requests, agent questions, and plan confirmations into a pending area instead of taking over the input box.
• Guidance queue: create, queue, and serially dispatch user guidance todos, with queue state recovered during active runs.
• Basic MCP integration: Claude stdio MCP servers can be managed by Lilia and injected into runtime; Codex stdio MCP servers can be read from and managed in ~/.codex/config.toml.
• Unified interaction protocol: unify plan confirmations, tool confirmations, and agent questions across backends.
• Unified Lilia protocol: review, fix suggestion, batch apply, context compact, Goal, memory, config diagnostics, and background-terminal cleanup stay in the user-facing workflow layer; session fork and provider session controls use runtime commands and dispatch internally by backend.
• File context: mention files, directories, images, and other context with @, with pasted or dropped attachments also supported.
• Intelligent model selection: Lilia does not yet automatically choose model level or reasoning intensity based on request type.
• Slash commands: open the composer / panel, run built-in commands and project commands from .lilia/commands, and write command execution results back to the task timeline; full backend-native command proxying is not yet supported.

• Claude conversations: start new turns through Claude Agent SDK query() and save the SDK session_id so the same task can resume.
• Claude Plan: mirror ExitPlanMode, route approval, cancellation, and revision through unified AskUser, then restore execution-phase permission mode after approval.
• Claude prompt suggestions: consume native prompt_suggestion events and surface them in the composer suggestion area.
• Claude history: search local Claude JSONL sessions, preview messages / timeline, import them as Lilia tasks, and continue from the attached SDK session.
• Claude Skills: manage user-level and project-level Skills, and pass enabled skill names into the SDK.
• Claude tool display: normalize common tools including Bash, Read / Write / Edit / MultiEdit, Glob / Grep, NotebookEdit, WebSearch / WebFetch, TodoWrite, Task / Agent, and ExitPlanMode.
• Claude Lilia protocol: review / fix suggestion / batch apply run through structured Claude prompts, session fork uses runtime command handling backed by the SDK, and Goal plus unsupported native-only actions write Lilia timeline diagnostics.
• Claude MCP management (partial): the UI can create, edit, delete, and enable stdio MCP servers; HTTP / SSE, OAuth, elicitation, tool policy, and SDK instance MCP are not yet integrated.
• Claude Plugins (partial): Lilia can discover and enable user-level local plugins, then pass enabled plugin paths to the SDK; installation, updates, project-level scope, and marketplace scope are not yet integrated.
• Claude Hooks (partial): the runtime registers a small SDK hook set and can display some hook lifecycle events; hooks configuration management and execution result panels are not yet available.
• Claude Subagents (partial): Task / Agent calls, task progress, and notifications can be displayed; subagent definitions, list management, and proactive scheduling UI are not yet available.

• Codex conversations: start or resume Codex app-server threads and save runtime state by task.
• Codex process display: show Codex reasoning, commands, file changes, searches, plans, and final replies.
• Codex environment checks: show whether the Codex CLI, app-server, API, and connection state are available.
• Codex Plan: enable the app-server experimental API, read the plan preset from collaborationMode/list, and pass collaborationMode to turn/start; after plan approval, Lilia explicitly returns to default mode for execution.
• Codex approval bridge: command and file-change approvals enter unified tool confirmation with additionalPermissions / availableDecisions, and Lilia can execute user-edited Codex commands before steering the result back to Codex.
• Codex MCP management: the UI can view, create, edit, delete, and enable user-level stdio MCP servers in ~/.codex/config.toml; HTTP / OAuth / unknown transports remain read-only.
• Codex profiles: support global and project-level profiles, reasoning effort, runtime workspace roots, controlled permissions, and sticky thread/settings/update.
• Codex history: search, preview, import, and continue existing Codex app-server threads from the left sidebar import entry.
• Codex Lilia adapter: the workflow layer handles review, fix suggestion, batch apply, compact, Goal, memory mode / reset, config diagnostics, and background-terminal cleanup; runtime commands handle session fork and session controls through Codex app-server methods.
• Built-in browser interaction: Codex can open and navigate an IAB window, collect page title / URL / screenshot metadata, and send the result back to the running turn or as a message attachment; screenshot capture is currently Windows-first.

• Project management (partial): local projects, Git clone, project ordering, pinning, removal, and session counts are available; project-level progress, data, and cost views are not yet integrated.
• Task-based conversations: conversations are persisted as tasks, with draft promotion, project conversations, orphan conversations, archiving, pinning, and ordering.
• Task tree (partial): the data layer has parent_id and depends_on, but full parent-child tree, dependency view, and blocker management UI are not yet available.
• Plugin system (partial): Claude Skills / Plugins / MCP and Codex MCP management can feed runtime extensions; a generic plugin system with selectable behavior plugins is not yet complete.
• Memory (partial): the project Memory tab and extension-host context candidate path exist; user-level / project-level memory storage, retrieval, and automatic injection are not yet user-facing.
• Roadmap and milestones (partial): the project Roadmap page can aggregate the current project's task state into a first-release milestone, progress, status distribution, current focus, and recently completed tasks; persisted Milestone / TaskMilestoneLink data sources are not yet integrated.
• Automatic orchestration: Lilia does not yet schedule multiple agents based on task state, dependencies, or user strategy.
• Helper agents: lower-cost agents do not yet run inside a session to supervise or assist the main agent.
• Built-in Lilia protocol: keep a single built-in runtime path.

The repository, package names, protocol names, and local configuration paths still use the lilia name to avoid breaking existing protocols and persistence paths.

Lilia/
├── apps/
│   └── desktop/                # Main app: Vue 3 + Tauri 2
│       ├── src/
│       │   ├── layouts/        # AppShell / SecondaryPanel / TitleBar
│       │   ├── components/     # ViewTabs / TodoFloat / ChatComposer, etc.
│       │   ├── pages/          # project/ProjectShell / TaskDetail / Settings
│       │   ├── services/       # projectsStore / tasksStore / todos / chat
│       │   ├── styles/         # Theme tokens, standard components, shell, and lazy page styles
│       │   ├── router.ts
│       │   └── mainBootstrap.ts
│       └── src-tauri/          # Tauri 2 Rust side
│           └── src/
│               ├── store.rs    # lilia-store: SQLite + r2d2 + migrations
│               ├── todos.rs    # Intercepts TodoWrite / todo_list events -> TaskTodo upsert
│               ├── plugins.rs  # Claude skills / plugins / MCP and Codex MCP management
│               └── lib.rs      # chat / settings / project / plugin IPC
└── packages/
    └── contracts/              # Shared TS types and timeline display rules

LiliaCode uses Yarn 4.14.1 through Corepack. Enable Corepack first, then run contributor commands from the repository root through the root yarn ... scripts. npm, pnpm, global Yarn 1.x, and direct workspace script entrypoints are guarded and not supported as the contributor path.

# 1) Enable Corepack and activate the repository Yarn version
corepack enable
corepack prepare yarn@4.14.1 --activate

# 2) Install dependencies
yarn install

# 3) Start only the Vite frontend
yarn dev

# 4) Start the Tauri desktop app (requires a local Rust toolchain and WebView2)
yarn tauri:dev

# 5) Run type checks, unit tests, Rust check, and contracts check
yarn verify

# 6) Start, build, or preview the documentation site
yarn docs:dev
yarn docs:build
yarn docs:preview

If yarn --version still reports 1.x after enabling Corepack, run commands through Corepack explicitly, for example corepack yarn install and corepack yarn dev. Repository scripts and workspace scripts enforce the same package-manager check so contributors hit one Corepack-managed Yarn path.

Windows first-release packaging is driven by the release workflow. Before tagging a release, sync the root package.json, apps/desktop/package.json, apps/desktop/src-tauri/Cargo.toml, and apps/desktop/src-tauri/tauri.conf.json versions, then run:

yarn release:check --tag vX.Y.Z

Pushing a v* tag runs yarn verify and yarn release:check --tag <tag>, builds the Windows Tauri installer, and uploads a draft GitHub Release. Keep the release as a draft until the Windows installer has been downloaded and manually verified for install, launch, basic window operation, and uninstall. Current release artifacts are Windows-only, unsigned, do not include the Tauri updater, and are upgraded manually by downloading and installing a newer package.

The Tauri icon source is apps/desktop/src-tauri/icons/icon.png. To regenerate the desktop PNG / ICO set through the Tauri CLI, run yarn icons:generate. yarn icons:tauri is kept as the same generation entrypoint.

• Codex provided important references for interface design and interaction organization; LiliaCode continues to iterate on top of those ideas.