You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
dist/bundled/ # Bundled skills & references shipped with the CLI
59
30
```
60
31
32
+
Templates for tool descriptions and prompts are at `packages/cli/dist/templates/` (copied during build from `packages/core/templates/`). Built-in skills are under `packages/cli/dist/bundled/`.
33
+
61
34
## Build, Test, and Development Commands
62
35
63
-
| Command | Purpose |
36
+
All commands run from the repo root.
37
+
38
+
| Command | What it does |
64
39
|---|---|
65
-
|`npm run typecheck`| TypeScript type checking (`tsc --noEmit`)|
66
-
|`npm run lint`| ESLint across `src/`|
40
+
|`npm run typecheck`| TypeScript type checking across all workspaces|
41
+
|`npm run lint`| ESLint across `packages/*/src/**/*.{ts,tsx}` + `scripts/*.js`|
67
42
|`npm run lint:fix`| ESLint with auto-fix |
68
-
|`npm run format`| Prettier on all `src/**/*.{ts,tsx}`|
43
+
|`npm run format`| Prettier on all source files|
69
44
|`npm run format:check`| Prettier in check-only mode |
70
45
|`npm run check`| Runs typecheck + lint + format:check together |
71
-
|`npm run bundle`| esbuild bundles cli + core + all deps → `dist/cli.js` (ESM, Node 22) |
Run the CLI locally for manual testing: `node dist/cli.js` (after `npm run bundle`).
59
+
Run the CLI locally for manual testing: `node packages/cli/dist/cli.js` (after `npm run bundle`).
77
60
78
61
## Coding Style & Naming Conventions
79
62
@@ -84,32 +67,34 @@ Run the CLI locally for manual testing: `node dist/cli.js` (after `npm run bundl
84
67
-**Line width**: 120 characters max
85
68
-**Line endings**: LF only
86
69
87
-
**TypeScript**: Strict mode enabled. Use `import type` for type-only imports (enforced by `@typescript-eslint/consistent-type-imports`). Unused variables prefixed with `_` are allowed.
70
+
**TypeScript**: Strict mode enabled (`strict: true`). Use `import type` for type-only imports (`@typescript-eslint/consistent-type-imports`). Unused variables prefixed with `_` are allowed (`argsIgnorePattern: "^_"`). Target ES2022, module ESNext with bundler resolution. JSX is `react-jsx`.
88
71
89
-
**Formatting/Linting**: Prettier + ESLint (typescript-eslint, react-hooks). Run `npm run check` before pushing. On commit, Husky + lint-staged auto-formats staged `*.{ts,tsx,js,mjs,cjs,ejs,jsx}` and `*.json` files.
72
+
**Formatting/Linting**: Prettier (double quotes, 2-space indent, semicolons) + ESLint (typescript-eslint, react-hooks). Run `npm run check` before pushing. On commit, Husky + lint-staged auto-formats staged `*.{ts,tsx,js,mjs,cjs,jsx}` and `*.json` files.
90
73
91
74
**File naming**: `kebab-case.ts` for modules, `kebab-case.tsx` for React/Ink components. Test files: `*.test.ts` (always kebab-case).
92
75
93
76
## Testing Guidelines
94
77
95
78
-**Framework**: Node.js native test runner (`node:test`) with `tsx` for TypeScript
96
79
-**Assertions**: `node:assert/strict`
97
-
-**Coverage**: Target meaningful unit tests for core logic (session management, tool handlers, settings resolution, prompt buffer, permissions, MCP client, telemetry). Test files are in `src/tests/` matching the source module name.
80
+
-**Coverage**: Target meaningful unit tests for core logic (session management, tool handlers, settings resolution, prompt buffer, permissions, MCP client, telemetry). Test files are in `packages/*/src/tests/` matching the source module name.
98
81
-**Test naming**: `describe`/`test` blocks with descriptive names. Example: `test("SessionManager preserves structured system content when building OpenAI messages", ...)`
99
82
-**Relaxed lint rules**: Test files allow `any` and unused vars.
100
-
- Run all tests with `npm test` before submitting a PR. A cross-platform test runner is available at `src/tests/run-tests.mjs`.
83
+
- Run all tests with `npm test` before submitting a PR. Each package has its own `run-tests.mjs` cross-platform runner.
101
84
102
85
## Commit & Pull Request Guidelines
103
86
104
-
**Commit messages** follow conventional commits. From the project history:
87
+
**Commit messages** follow conventional commits:
105
88
106
89
-`feat:` — new feature (e.g., `feat: add /model command`)
@@ -120,22 +105,23 @@ Run the CLI locally for manual testing: `node dist/cli.js` (after `npm run bundl
120
105
121
106
## Architecture Overview
122
107
123
-
The CLI (`@vegamo/deepcode-cli`) renders a terminal UI using [Ink](https://github.com/vadimdemedes/ink) (React for terminals). `SessionManager` drives the LLM interaction loop: it builds system prompts, sends user messages with optional skills/images, streams responses, executes tool calls via `ToolExecutor`, and compacts context when token thresholds are exceeded (512K for DeepSeek V4 models, 128K for others). OpenAI client connectivity is managed by `createOpenAIClient()`in `src/common/openai-client.ts`, which caches the client singleton and applies a 180-second keep-alive timeout.
108
+
The CLI (`@vegamo/deepcode-cli`) renders a terminal UI using [Ink](https://github.com/vadimdemedes/ink) (React for terminals). `SessionManager`(in `@vegamo/deepcode-core`) drives the LLM interaction loop: it builds system prompts, sends user messages with optional skills/images, streams responses, executes tool calls via `ToolExecutor`, and compacts context when token thresholds are exceeded (512K for DeepSeek V4 models, 128K for others). OpenAI client connectivity is managed by `createOpenAIClient()`with a 180-second keep-alive timeout.
124
109
125
-
Seven built-in tools are available to the LLM: `bash`, `read`, `write`, `edit`, `AskUserQuestion`, `UpdatePlan`, and `WebSearch`. Tool definitions are registered in `src/tools/executor.ts` and described to the LLM via `src/prompt.ts` and `templates/tools/`. The `UpdatePlan` tool enables the LLM to display and update a structured task list in the terminal.
110
+
Seven built-in tools are available to the LLM: `bash`, `read`, `write`, `edit`, `AskUserQuestion`, `UpdatePlan`, and `WebSearch`. Tool definitions are registered in `packages/core/src/tools/executor.ts` and described to the LLM via `packages/core/src/prompt.ts`.
126
111
127
-
A **permission system** (`src/common/permissions.ts`) controls tool execution scopes (read/write/delete/network/git-log, etc.) with configurable allow/deny/ask decisions. The `PermissionPrompt` view presents interactive prompts when a tool requires user approval.
112
+
A **permission system** (`packages/core/src/common/permissions.ts`) controls tool execution scopes (read/write/delete/network/git-log, etc.) with configurable allow/deny/ask decisions.
128
113
129
-
A **file history system** (`src/common/file-history.ts`) provides undo/checkpoint support by creating lightweight Git branches per session. The `GitFileHistory` class manages blob storage and branch references via a `.deepcode-file-history.json` manifest.
114
+
A **file history system** (`packages/core/src/common/file-history.ts`) provides undo/checkpoint support via lightweight Git branches.
130
115
131
-
**Slash commands**: `/model`, `/new`, `/init`, `/resume`, `/continue`, `/mcp`, `/exit`, plus dynamic `/skill-name` for each loaded skill.
116
+
**Slash commands**: `/skills`, `/model`, `/new`, `/init`, `/resume`, `/continue`, `/undo`, `/mcp`, `/raw`, `/exit`, plus dynamic `/skill-name` for each loaded skill.
132
117
133
-
**Key UI features**: `@` file mentions in the prompt input (scans project files), `Ctrl+O` to view live process stdout in fullscreen, `Ctrl+V` to paste images, MCP server status display, undo selector, and permission prompts.
118
+
**Key UI features**: `@` file mentions in the prompt input, `Ctrl+O` to view live process stdout, `Ctrl+V` to paste images, Shift+Enter for newlines, MCP server status display, undo selector, and permission prompts.
134
119
135
120
**CLI flags**: `-p <prompt>` / `--prompt` to auto-submit a prompt on launch, `-v` / `--version`, `-h` / `--help`.
136
121
137
122
## Agent-Specific Instructions
138
123
139
-
-**AGENTS.md loading**: The CLI loads agent instructions from `./AGENTS.md`, `./.deepcode/AGENTS.md`, or `~/.deepcode/AGENTS.md` (first found wins). Write project-specific guidance for the LLM in any of these.
124
+
-**AGENTS.md loading**: The CLI loads agent instructions from `./AGENTS.md`, `./.deepcode/AGENTS.md`, or `~/.deepcode/AGENTS.md` (first found wins).
140
125
-**Skills**: Place skill definitions in `~/.agents/skills/<name>/SKILL.md` (user-level) or `./.agents/skills/<name>/SKILL.md` (project-level). Legacy path `./.deepcode/skills/` is also supported. Each SKILL.md uses YAML frontmatter with `name` and `description` fields.
141
-
-**Built-in skills**: `agent-drift-guard` (detects and corrects execution drift), `plan-and-execute` (structured task planning with progress tracking), and `karpathy-guidelines` (behavioral guidelines to reduce common LLM coding mistakes). All three are defined in `templates/skills/` and always injected into every session.
126
+
-**Built-in skills**: Four bundled skills ship with the CLI — `plan` (task planning workflow), `deepcode-self-refer` (Deep Code CLI documentation), `skill-digester` (digest & install skills), `skill-writer` (create & debug skills). Additionally, `karpathy-guidelines` (behavioral guidelines to reduce LLM coding mistakes) is injected as a default skill template.
127
+
-**Prompt file references**: Use `@path/to/file` syntax in prompts to load file contents through the read tool.
0 commit comments