ChatCrystal: Instructions file for Codex

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Project Overview

ChatCrystal is an AI conversation knowledge crystallization tool. It imports conversations from AI coding tools (Claude Code, Cursor, Codex CLI, Trae, GitHub Copilot), uses LLM to generate structured notes (title, summary, key conclusions, code snippets, tags), and provides semantic search via embeddings. The UI is in Simplified Chinese.

Commands

# Install (Node.js 24; root workspace uses pnpm via Corepack)
corepack enable
pnpm install

# Development (server port 3721 + client port 13721)
pnpm dev

# Build for production
pnpm build

# Production server (serves frontend statically on port 3721)
pnpm start

# Electron desktop app
pnpm dev:electron        # dev mode (Vite HMR + Electron window)
pnpm build:electron      # build NSIS installer → release/
pnpm pack:electron       # build unpacked directory (faster for testing)

# Release (bump version + git tag + push → CI builds & publishes)
pnpm release             # patch bump (0.1.0 → 0.1.1)
pnpm release -- minor    # minor bump
pnpm release -- major    # major bump
pnpm release -- 1.0.0    # explicit version
pnpm release:electron -- 1.0.1  # Electron-only release → electron-v*
pnpm release:npm -- 1.0.1       # npm-only release → npm-v*

# Lint
pnpm lint
pnpm lint:fix

# Tests (all layers by default)
pnpm test
pnpm test:server
pnpm test:client
pnpm test:electron
pnpm --filter ./server smoke:mcp  # requires pnpm build first

# Dependency security
pnpm security:audit
pnpm security:signatures

Release Tag Semantics

Use scripts/release.mjs for releases; do not manually bump versions, commit, tag, and push unless the user explicitly asks for a custom recovery flow.

• v* tags are full releases and trigger both npm publishing and Electron GitHub Release builds. Use this only when both root package.json and server/package.json should move together.
• electron-v* tags are Electron-only releases. Use pnpm release:electron -- <version> for desktop-only changes, including Electron main/preload/tray/packaging changes and Electron-gated client UI.
• npm-v* tags are npm-only releases. Use pnpm release:npm -- <version> for CLI/server/MCP package changes.
• The published npm package version comes from server/package.json, not the root package. If a v* tag is pushed while server/package.json still points at an already-published version, the npm job will fail with E403 You cannot publish over the previously published versions.
• If an Electron-only release is accidentally published with a v* tag and the Electron job succeeds but npm fails because the server version already exists, do not delete or re-tag the release by default. Treat the GitHub Release as usable, document the cause, and use electron-v* for the next Electron-only release.