Windcode

Windcode 是一个Coding Agent。它可以在本地工作区中读取和修改代码、执行命令、运行测试、恢复会话，并通过权限策略与 Linux 沙箱控制高风险操作。

alt text

功能

Textual 终端工作台与 Python SDK
Anthropic Messages、OpenAI Responses 和 OpenAI-compatible 模型协议
流式输出、工具调用、审批、取消、重试与显式模型回退
会话恢复、历史回退、上下文压缩和本地 trace
多子智能体并行执行与独立 Worktree
项目级长期记忆：用户画像、项目事实、经验、SOP 与主动查询
MCP Server、Skills、Hooks 和本地插件扩展
四种权限模式与 Linux Bubblewrap、macOS Seatbelt、Windows helper 沙箱后端

快速开始

环境要求：Linux、macOS 或 Windows，Python 3.11+、uv。

Linux 使用 Bubblewrap，macOS 使用 Seatbelt。Windows wheel 随包携带 Rust helper，使用按读写与网络能力分离的 AppContainer 身份、workspace ACL、SID 绑定的 WFP/Windows Firewall 规则和 kill-on-close Job Object。首次使用需在“以管理员身份运行”的终端执行：

windcode sandbox setup --json
windcode sandbox status --json

只有 helper 同时报告文件、网络和进程隔离已就绪时才自动执行；初始化缺失、规则被删除或协议版本不匹配都会 fail closed，并要求显式批准单次沙箱外运行。

沙箱 preset 为 read_only、默认的 workspace_write 和显式的 danger_full_access。旧配置 enabled=true/false 仍可读取，并分别映射到 workspace_write/danger_full_access。命令联网和沙箱外运行单独审批；项目级命令前缀规则保存在 state root 的 permissions/projects/，不会写入仓库。

从 PyPI 安装命令行工具：

uv tool install windcode
windcode /path/to/project

也可以安装到当前 Python 环境：

uv pip install windcode

从源码运行：

uv sync --frozen --all-groups
cp .windcode/config.toml.example .windcode/config.toml
uv run windcode /path/to/project

最小模型配置：

primary_provider = "primary"

[providers.primary]
protocol = "openai_compatible"
model = "your-model"
base_url = "https://example.com/v1"
api_key_env = "MODEL_API_KEY"

密钥应通过环境变量或 Windcode 凭据存储提供，不要写入项目配置。

export MODEL_API_KEY="..."
uv run windcode .

常用启动参数：

--config FILE
--model PROVIDER_OR_MODEL
--resume SESSION_ID
--permission-mode plan|default|accept_edits|full_access
--sandbox / --no-sandbox

常用命令

/new                         新建会话
/resume [SESSION_ID]         恢复会话
/history                     查看历史节点
/rewind RECORD_ID            回退到历史记录
/model                       管理模型与 Provider
/mode MODE                   切换权限模式
/memory                      管理长期记忆
/extensions                  管理扩展
/compact                     压缩当前上下文
/agents                      查看子智能体
/status                      查看运行状态

MCP Server

[extensions]
enabled = true

[extensions.mcp_servers.example]
transport = "streamable_http"
url = "https://example.com/mcp"
enable = true
required = false

enable = false 的服务器不会连接、不会参与工具搜索，也不会注入模型上下文。required 只在服务器启用时表示启动阶段必须连接成功。扩展系统和内置的 gaodemap-mcp 默认开启。

本地状态

Windcode 将记忆、会话、trace、扩展状态和 Worktree 统一存放在选定的状态根下：

[storage]
project_state_root = ".windcode"
user_storage_root = "~/.windcode"

用户级配置固定读取 ~/.windcode/config.toml；项目中的 .windcode/config.toml 优先级更高。配置项目状态根时优先使用项目目录；未配置时使用 ~/.windcode。Skill 会同时扫描两边的 skill/，同名时项目级覆盖用户级。项目 .windcode/config.toml 和 .windcode/ 下的运行状态都不应提交到 Git。

开发

uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest -q
uv build

构建与发布

发布前更新 pyproject.toml 和 src/windcode/__init__.py 中的版本号，并完成完整检查：

uv sync --frozen --all-groups
uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest -q
uv build --no-sources

可以先发布到 TestPyPI 验证：

uv publish \
  --publish-url https://test.pypi.org/legacy/ \
  --token "$TEST_PYPI_TOKEN"

正式版本通过 GitHub Release 自动发布：创建与项目版本一致的标签，例如 v0.1.0，然后发布 GitHub Release。.github/workflows/publish.yml 会验证标签、运行测试、构建发行包，并使用 PyPI Trusted Publishing 发布。首次发布前需要在 PyPI 配置以下 Trusted Publisher：

Owner: tingfeng347
Repository: windcode
Workflow: publish.yml
Environment: pypi

PyPI 不允许覆盖已经发布的同名版本；重新发布前必须增加版本号。

生产代码位于 src/windcode/。本地 tests/ 与 spec/ 目录由 Git 忽略，仅用于开发和规格管理。

License

Apache-2.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

windcode-0.2.1.tar.gz (5.2 MB view details)

Uploaded Jul 16, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

windcode-0.2.1-py3-none-win_arm64.whl (454.4 kB view details)

Uploaded Jul 16, 2026 Python 3Windows ARM64

windcode-0.2.1-py3-none-win_amd64.whl (466.7 kB view details)

Uploaded Jul 16, 2026 Python 3Windows x86-64

windcode-0.2.1-py3-none-any.whl (257.0 kB view details)

Uploaded Jul 16, 2026 Python 3

File details

Details for the file windcode-0.2.1.tar.gz.

File metadata

Download URL: windcode-0.2.1.tar.gz
Upload date: Jul 16, 2026
Size: 5.2 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for windcode-0.2.1.tar.gz
Algorithm	Hash digest
SHA256	`d5367fe40c3fba757e5b13ff970951aa89985888f0bbb59e4117d278d0900c6d`
MD5	`5ea573bb8d90a0b82ae20b277467f042`
BLAKE2b-256	`be57029a3a48610bce5002777d89cfd63a8b80a9a0ccbc787674fa8bbb29e51a`

See more details on using hashes here.

Provenance

The following attestation bundles were made for windcode-0.2.1.tar.gz:

Publisher: publish.yml on tingfeng347/windcode

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: windcode-0.2.1.tar.gz
- Subject digest: d5367fe40c3fba757e5b13ff970951aa89985888f0bbb59e4117d278d0900c6d
- Sigstore transparency entry: 2179324073
- Sigstore integration time: Jul 16, 2026
Source repository:
- Permalink: tingfeng347/windcode@8c4d2f6fa6b60f105a8ba1fdb54c46494ad4521b
- Branch / Tag: refs/tags/v0.2.1
- Owner: https://github.com/tingfeng347
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@8c4d2f6fa6b60f105a8ba1fdb54c46494ad4521b
- Trigger Event: release

File details

Details for the file windcode-0.2.1-py3-none-win_arm64.whl.

File metadata

Download URL: windcode-0.2.1-py3-none-win_arm64.whl
Upload date: Jul 16, 2026
Size: 454.4 kB
Tags: Python 3, Windows ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for windcode-0.2.1-py3-none-win_arm64.whl
Algorithm	Hash digest
SHA256	`7c3c9734256869956ef92230332246ef4d572848d5886f96c75b0430a70674b1`
MD5	`ea9f30f09f3bf6122808794719d379d1`
BLAKE2b-256	`9d36b0c8a6c2b96483652dbe26a521a34633d59061b36213ad99862c239d422d`

See more details on using hashes here.

Provenance

The following attestation bundles were made for windcode-0.2.1-py3-none-win_arm64.whl:

Publisher: publish.yml on tingfeng347/windcode

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: windcode-0.2.1-py3-none-win_arm64.whl
- Subject digest: 7c3c9734256869956ef92230332246ef4d572848d5886f96c75b0430a70674b1
- Sigstore transparency entry: 2179324129
- Sigstore integration time: Jul 16, 2026
Source repository:
- Permalink: tingfeng347/windcode@8c4d2f6fa6b60f105a8ba1fdb54c46494ad4521b
- Branch / Tag: refs/tags/v0.2.1
- Owner: https://github.com/tingfeng347
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@8c4d2f6fa6b60f105a8ba1fdb54c46494ad4521b
- Trigger Event: release

File details

Details for the file windcode-0.2.1-py3-none-win_amd64.whl.

File metadata

Download URL: windcode-0.2.1-py3-none-win_amd64.whl
Upload date: Jul 16, 2026
Size: 466.7 kB
Tags: Python 3, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for windcode-0.2.1-py3-none-win_amd64.whl
Algorithm	Hash digest
SHA256	`d0ed43887d4b44847d05630eb0a9e1ddabed998f44707ef7c609eea17ebbc8fa`
MD5	`fb1de1c569229807d74836ff73cc83ac`
BLAKE2b-256	`9aaa12b62b8dd774f4ef9bb18055fa02783ba9645c15c73cffa5a89f2d2814f8`

See more details on using hashes here.

Provenance

The following attestation bundles were made for windcode-0.2.1-py3-none-win_amd64.whl:

Publisher: publish.yml on tingfeng347/windcode

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: windcode-0.2.1-py3-none-win_amd64.whl
- Subject digest: d0ed43887d4b44847d05630eb0a9e1ddabed998f44707ef7c609eea17ebbc8fa
- Sigstore transparency entry: 2179324273
- Sigstore integration time: Jul 16, 2026
Source repository:
- Permalink: tingfeng347/windcode@8c4d2f6fa6b60f105a8ba1fdb54c46494ad4521b
- Branch / Tag: refs/tags/v0.2.1
- Owner: https://github.com/tingfeng347
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@8c4d2f6fa6b60f105a8ba1fdb54c46494ad4521b
- Trigger Event: release

File details

Details for the file windcode-0.2.1-py3-none-any.whl.

File metadata

Download URL: windcode-0.2.1-py3-none-any.whl
Upload date: Jul 16, 2026
Size: 257.0 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for windcode-0.2.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`b04ef632f2e3b8926f52103eea1e5959c05742ca5fb697fa98fa050ebf47e0e3`
MD5	`1e2fe72e73d5dad06b5530312b213480`
BLAKE2b-256	`438157766e86233cd5203d626020e3f3e352b5c9c0334ab85caaf962300d99af`

See more details on using hashes here.

Provenance

The following attestation bundles were made for windcode-0.2.1-py3-none-any.whl:

Publisher: publish.yml on tingfeng347/windcode

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: windcode-0.2.1-py3-none-any.whl
- Subject digest: b04ef632f2e3b8926f52103eea1e5959c05742ca5fb697fa98fa050ebf47e0e3
- Sigstore transparency entry: 2179324205
- Sigstore integration time: Jul 16, 2026
Source repository:
- Permalink: tingfeng347/windcode@8c4d2f6fa6b60f105a8ba1fdb54c46494ad4521b
- Branch / Tag: refs/tags/v0.2.1
- Owner: https://github.com/tingfeng347
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@8c4d2f6fa6b60f105a8ba1fdb54c46494ad4521b
- Trigger Event: release