[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81615":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":8,"htmlUrl":8,"language":9,"languages":8,"totalLinesOfCode":8,"stars":10,"forks":11,"watchers":12,"openIssues":12,"contributorsCount":11,"subscribersCount":11,"size":11,"stars1d":11,"stars7d":11,"stars30d":13,"stars90d":11,"forks30d":11,"starsTrendScore":11,"compositeScore":14,"rankGlobal":8,"rankLanguage":8,"license":15,"archived":16,"fork":16,"defaultBranch":17,"hasWiki":18,"hasPages":16,"topics":19,"createdAt":8,"pushedAt":8,"updatedAt":20,"readmeContent":21,"aiSummary":22,"trendingCount":11,"starSnapshotCount":11,"syncStatus":23,"lastSyncTime":24,"discoverSource":25},81615,"pi-codemode","boozedog\u002Fpi-codemode","boozedog",null,"TypeScript",23,0,22,1,37.1,"MIT License",false,"master",true,[],"2026-06-12 04:01:34","# Pi Codemode\n\nPi Codemode is a Pi extension that replaces many small tool calls with one typed `execute_tools` call. The model writes a TypeScript code body, Pi type-checks it, then runs it in a sandbox with explicit tool globals.\n\n## Quickstart\n\nInstall the package in Pi as an extension package, then start Pi in a project as usual. Codemode starts in configured mode; the default is `on`, which exposes `execute_tools` plus Pi's normal non-bash tools.\n\nUseful controls:\n\n- `\u002Fcodemode on` exposes `execute_tools` plus normal non-bash tools.\n- `\u002Fcodemode yolo` exposes everything from `on` plus native `bash` when available.\n- `\u002Fcodemode off` restores normal Pi tools.\n- Bare `\u002Fcodemode` toggles `off \u003C-> on`.\n\n## The `execute_tools` shape\n\n`execute_tools` accepts a TypeScript **code body**, not a full function:\n\n```ts\nconst pkg = await read({ path: \"package.json\" });\nprint(\"package bytes\", pkg.length);\nreturn JSON.parse(pkg).name;\n```\n\nReturn a value to include it in the tool result. `print()` and `console.log()` output is captured before the return value. Type errors are reported before execution, so invalid code has no side effects. Runtime errors are returned as tool errors.\n\nLarge codemode calls, results, and file diffs render compactly in Pi by hiding their middle section. Use `Ctrl+O` to expand the hidden content, and `Ctrl+O` again to collapse.\n\n## Built-in globals\n\nGenerated code only receives explicit globals:\n\n- `read({ path, offset?, limit? })` reads a project file.\n- `write({ path, content })` writes a project file, creating parent directories.\n- `edit({ path, edits })` performs exact text replacements.\n- `codemode.search_tools({ query })` searches available Pi\u002FMCP tools.\n- `codemode.list_mcp_servers()` lists configured MCP namespaces.\n- `codemode.list_tools({ namespace, offset?, limit? })` lists cached MCP tools with pagination.\n- `codemode.describe_tools({ namespace, tool? })` shows MCP namespace\u002Ftool details.\n- `codemode.plan_npm_script({ script })` decomposes a safe package script into visible `cli.*` calls without executing it.\n- `codemode.run_npm_script({ script, verbose? })` decomposes a safe package script, shows the plan, and executes only the surfaced `cli.*` calls.\n- `codemode.\u003Cnamespace>.\u003Ctool>(args)` calls configured MCP tools.\n- `cli.\u003Ctool>.\u003Coperation>(args)` calls configured typed CLI capabilities.\n- `print(...args)` emits result output.\n- `π.key` reads string constants passed in the `strings` parameter.\n\n### File edits\n\n`edit` mirrors Pi's exact replacement model:\n\n```ts\nawait edit({\n  path: \"src\u002Findex.ts\",\n  edits: [{ oldText: \"const oldName =\", newText: \"const newName =\" }],\n});\n```\n\nEach `oldText` must match exactly once in the original file. Edits in one call must not overlap. Merge nearby changes into one larger replacement.\n\n### Hard-to-quote strings with `π`\n\nUse `strings` for file content that contains backticks, `${...}`, nested quotes, code blocks, or shell scripts:\n\n```json\n{\n  \"code\": \"await write({ path: 'script.sh', content: π.script });\",\n  \"strings\": {\n    \"script\": \"#!\u002Fusr\u002Fbin\u002Fenv bash\\necho \\\"hello ${USER}\\\"\\n\"\n  }\n}\n```\n\nInside code, `π.script` is a normal string. The `strings` values only need JSON escaping, not JavaScript string-literal escaping.\n\n### Parallel calls\n\nUse `Promise.all` for independent work:\n\n```ts\nconst [pkg, tsconfig, readme] = await Promise.all([\n  read({ path: \"package.json\" }),\n  read({ path: \"tsconfig.json\" }),\n  read({ path: \"README.md\" }),\n]);\nreturn { files: [pkg.length, tsconfig.length, readme.length] };\n```\n\n## CLI capabilities\n\nCodemode does not expose a shell-string API. There is no `$`, `shell()`, `bash -c`, or raw argv passthrough in generated code. Instead, configured typed command capabilities are exposed under `cli`:\n\n```ts\nconst status = await cli.git.status({ short: true, branch: true });\nconst hits = await cli.rg.search({ pattern: \"TODO\", paths: [\"src\"], lineNumber: true });\n```\n\nEach `cli` tool\u002Foperation must be allowlisted in config. Backends may be native host commands or `just-bash` commands. `just-bash` backend operations are explicitly limited to read-only operation metadata and must exist in the installed `just-bash` command set; discovery is used for validation only and never auto-exposes commands. `just-bash` still uses scoped mounts internally, typically `\u002Fworkspace` mapped to the project root read\u002Fwrite and `\u002Ftmp` as in-memory temp space. Network and JS\u002FPython runtimes remain disabled by default.\n\nHost command output is capped inline at 50 KiB per stream, with a truncation marker when exceeded. Non-zero command exits do not throw; inspect `exitCode`. Denied operations, missing executables, timeouts, and invalid runtime argument shapes throw clear CLI errors.\n\nGitHub issue relationship operations are intentionally curated. Codemode exposes narrow helpers matching GitHub's first-class issue dependency endpoint names: `cli.gh.issueListBlockedBy()`, `cli.gh.issueAddBlockedBy()`, and `cli.gh.issueListBlocking()`. These are backed by `GET\u002FPOST \u002Frepos\u002F{owner}\u002F{repo}\u002Fissues\u002F{issue_number}\u002Fdependencies\u002Fblocked_by` and `GET \u002Frepos\u002F{owner}\u002F{repo}\u002Fissues\u002F{issue_number}\u002Fdependencies\u002Fblocking`. Codemode does not expose generic `gh api` or arbitrary GraphQL execution to generated code; host code constructs the exact endpoint and resolves blocking issue numbers to same-repository REST database IDs internally.\n\n### npm script decomposition\n\nCodemode treats npm scripts as recipes to inspect, not shell commands to execute. Generated code should not call `npm`, `npx`, `node`, `bash`, or other abstraction layers directly. Instead, use the codemode npm-script helpers:\n\n```ts\nreturn await codemode.plan_npm_script({ script: \"build\" });\n```\n\nFor a package script such as:\n\n```json\n{\n  \"scripts\": {\n    \"build\": \"tsc\",\n    \"check\": \"npm run format:check && npm run lint && npm run build && npm test\",\n    \"format:check\": \"oxfmt . --check\",\n    \"lint\": \"oxlint --deny warnings --vitest-plugin src\",\n    \"test\": \"vitest run\"\n  }\n}\n```\n\nthe plan is surfaced as explicit calls:\n\n```text\nPlan for npm run check:\n- cli.oxfmt.check({\"paths\":[\".\"]})\n- cli.oxlint.run({\"deny\":\"warnings\",\"vitestPlugin\":true,\"paths\":[\"src\"]})\n- cli.tsc.build({})\n- cli.vitest.run({})\n\nNo commands were executed.\n```\n\nTo run the safe plan:\n\n```ts\nreturn await codemode.run_npm_script({ script: \"check\" });\n```\n\n`run_npm_script` prints the plan, executes only the surfaced `cli.*` calls, and stops on the first non-zero exit. By default, successful step output is compact; pass `verbose: true` to include stdout\u002Fstderr from successful steps:\n\n```ts\nreturn await codemode.run_npm_script({ script: \"check\", verbose: true });\n```\n\nScripts fail loudly before execution if they contain unsupported shell constructs, env expansion, command substitution, pipes\u002Fredirection, recursive cycles, or denied commands such as `node`, `npm`, `npx`, `bash`, or `python` outside the safe recursive `npm run \u003Cscript>` \u002F `npm test` subset.\n\nOperation-specific timeouts can be configured with object-form `operations`:\n\n```json\n{\n  \"cli\": {\n    \"rg\": {\n      \"backend\": \"host\",\n      \"operations\": {\n        \"search\": { \"timeoutMs\": 5000 }\n      }\n    }\n  }\n}\n```\n\n## MCP discovery workflow\n\nMCP tools are exposed under `codemode.*` only:\n\n```ts\nconst github = await codemode.describe_tools({ namespace: \"github\" });\nprint(github);\n\nconst details = await codemode.describe_tools({ namespace: \"github\", tool: \"search_issues\" });\nprint(details);\n\nreturn await codemode.github.search_issues({ query: \"is:open label:bug\" });\n```\n\nUse `codemode.list_mcp_servers()` to see available namespaces and `codemode.list_tools({ namespace })` to page through large cached tool lists. Use `codemode.search_tools({ query })` when you do not know the namespace or exact tool name.\n\n## Configuration\n\nCodemode loads JSON config from:\n\n1. `~\u002F.pi\u002Fagent\u002Fcodemode.json`\n2. `$PROJECT\u002F.pi\u002Fcodemode.json`\n\nProject config overrides global config. See `examples\u002Fcodemode.json` for a starter configuration with typed `git`, `gh`, `rg`, `find`, `grep`, and `ls` capabilities.\n\nDefault config:\n\n```json\n{\n  \"mode\": \"on\",\n  \"executor\": {\n    \"type\": \"quickjs\",\n    \"timeoutMs\": 120000\n  }\n}\n```\n\n`mode` can be `\"on\"`, `\"yolo\"`, or `\"off\"`. In `on`, Codemode exposes `execute_tools` plus normal non-bash tools. In `yolo`, native `bash` is included if Pi provides it; if not, codemode gracefully falls back to normal codemode tools and notifies you.\n\nCodemode-specific MCP servers and typed CLI capabilities can also be configured here:\n\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"github-mcp\": { \"command\": \"github-mcp\" }\n    }\n  },\n  \"cli\": {\n    \"git\": {\n      \"backend\": \"host\",\n      \"operations\": [\n        \"status\",\n        \"branch\",\n        \"diff\",\n        \"log\",\n        \"show\",\n        \"remote\",\n        \"revParse\",\n        \"add\",\n        \"commit\",\n        \"push\",\n        \"pull\",\n        \"switch\",\n        \"checkout\",\n        \"restore\",\n        \"reset\",\n        \"stash\",\n        \"tag\"\n      ]\n    },\n    \"gh\": {\n      \"backend\": \"host\",\n      \"operations\": [\n        \"issueView\",\n        \"issueList\",\n        \"issueCreate\",\n        \"issueEdit\",\n        \"issueComment\",\n        \"issueClose\",\n        \"labelCreate\",\n        \"labelList\",\n        \"prView\",\n        \"prList\",\n        \"prDiff\",\n        \"prChecks\",\n        \"prStatus\"\n      ]\n    },\n    \"rg\": { \"backend\": \"host\", \"operations\": [\"search\"] },\n    \"find\": { \"backend\": \"just-bash\", \"operations\": [\"files\"] },\n    \"grep\": { \"backend\": \"just-bash\", \"operations\": [\"search\"] },\n    \"ls\": { \"backend\": \"just-bash\", \"operations\": [\"list\"] },\n    \"vitest\": { \"backend\": \"host\", \"operations\": [\"run\"] },\n    \"tsc\": { \"backend\": \"host\", \"operations\": [\"build\"] },\n    \"oxfmt\": { \"backend\": \"host\", \"operations\": [\"check\", \"write\"] },\n    \"oxlint\": { \"backend\": \"host\", \"operations\": [\"run\"] },\n    \"vp\": { \"backend\": \"host\", \"operations\": [\"fmtCheck\", \"fmtWrite\"] }\n  }\n}\n```\n\n`quickjs` is the default MVP executor. `deno` is optional\u002Ffuture support behind the same executor interface; if selected and unavailable, `execute_tools` reports a configured-executor runtime error.\n\n## Security model\n\nGenerated code is untrusted. The host dispatcher is the authority.\n\nDenied by default:\n\n- direct Node globals such as `process` and `require`\n- direct filesystem access from generated code\n- direct environment access\n- direct network access\n- subprocess spawning from generated code\n- unrestricted host bash or shell strings inside generated code\n\nIn `yolo` mode, Pi's native `bash` tool is available outside `execute_tools` as an explicit escape hatch and has broader host access. Use `on` mode when you want Codemode without the native bash escape hatch.\n\n- raw subprocess\u002Fargv passthrough from generated code\n- just-bash network and JS\u002FPython runtimes\n\nAllowed capabilities are only the injected globals listed above. File tools validate paths against the project root and reject traversal outside it. Enabling host-backed `cli` operations expands trust boundaries and should be reviewed in config.\n\n## Installation\n\n### Recommended install: npm package\n\nPi Codemode is published as a Pi package on npm and is discoverable in the `pi.dev` package catalog because `package.json` includes the `pi-package` keyword and a Pi extension manifest.\n\n```sh\npi install npm:@boozedog\u002Fpi-codemode\n```\n\nTo try the npm package for one Pi run without adding it to settings:\n\n```sh\npi -e npm:@boozedog\u002Fpi-codemode\n```\n\n### Alternative install: tagged GitHub release\n\nPi Codemode is distributed through normal Pi extension package installs using GitHub release tags. This does not require cloning this repository to a fixed local path:\n\n```sh\npi install git:github.com\u002Fboozedog\u002Fpi-codemode@\u003Ctag>\n```\n\nTo try a tagged release for one Pi run without adding it to settings:\n\n```sh\npi -e git:github.com\u002Fboozedog\u002Fpi-codemode@\u003Ctag>\n```\n\nFor unpinned development installs from GitHub, update with:\n\n```sh\npi update git:github.com\u002Fboozedog\u002Fpi-codemode\n# or update all Pi extensions\npi update --extensions\n```\n\nFor local development, keep using a path install from this checkout:\n\n```sh\nnpm install\nnpm run build\npi install \u002Fabsolute\u002Fpath\u002Fto\u002Fpi-codemode\n```\n\nThe package manifest points Pi at `.\u002Fdist\u002Findex.js`. Runtime packages are normal `dependencies`; Pi-provided APIs are declared as `peerDependencies`. Git installs run `npm install`, and the package `prepare` script builds `dist\u002F` after install. npm publishes run `prepack`, which also builds `dist\u002F` before creating the tarball.\n\n## Development\n\n```sh\nnpm install\nnpm test\nnpm run build\nnpm run check\n```\n\nInside Codemode itself, prefer the surfaced npm-script workflow instead of direct `npm run` execution:\n\n```ts\nawait codemode.plan_npm_script({ script: \"check\" });\nawait codemode.run_npm_script({ script: \"check\" });\n```\n\nSource lives in `src\u002F`; generated build output lives in `dist\u002F`.\n\n## Release checklist\n\nTo bump the version, run the release helper from a clean tree:\n\n```sh\nnpm run release -- --version 0.1.3\n```\n\nTo publish the current `package.json` version without bumping:\n\n```sh\nnpm run release\n```\n\nThe helper checks for a clean tree, updates `package.json`\u002F`package-lock.json` when `--version` is provided, runs `npm run check`, commits the version bump, verifies package contents with `npm pack --dry-run`, then creates and pushes `v$npm_package_version`.\n\nAfter the tag is pushed:\n\n1. From a clean directory or machine, install the tag with `pi install git:github.com\u002Fboozedog\u002Fpi-codemode@\u003Ctag>`.\n2. Start Pi and confirm Codemode loads, `execute_tools` can read files, typed CLI\u002Fshell capabilities work, and the result UI renders.\n3. Publish the same version to npm for the Pi package catalog.\n\n### Publish to npm for pi.dev catalog discovery\n\nMake sure you are logged in to npm as an account with publish rights for `@boozedog\u002Fpi-codemode`, then run:\n\n```sh\nnpm run publish:npm\n```\n\nThe publish helper runs checks, verifies the tree is clean, dry-runs the package tarball, and publishes with `--access public`. Once npm indexes the package, `https:\u002F\u002Fpi.dev\u002Fpackages` discovers it from the `pi-package` keyword.\n","Pi Codemode 是一个用于 Pi 的扩展工具，它通过单一的 `execute_tools` 调用来替代多个小型工具的调用。核心功能包括允许用户编写 TypeScript 代码片段来执行文件读写、编辑等操作，并且在运行前会进行类型检查以确保代码的有效性，从而避免了潜在的运行时错误。此外，该工具还支持对项目文件进行精确修改以及安全地规划和执行 npm 脚本等功能。Pi Codemode 适用于需要简化开发流程、提高编码效率同时保证代码质量的场景，特别适合那些希望利用 TypeScript 的强大类型系统来增强其开发体验的开发者。",2,"2026-06-11 04:05:43","CREATED_QUERY"]