Content
# Windcode
Windcode is a Coding Agent. It can read and modify code, execute commands, run tests, restore sessions, and interact with a Linux sandbox through permission policies to control high-risk operations.
## Features
- Textual terminal workspace with Python SDK
- Anthropic Messages, OpenAI Responses, and OpenAI-compatible model protocols
- Streaming output, tool calls, approvals, cancellations, retries, and explicit model fallbacks
- Session restoration, history rewind, context compression, and local tracing
- Multi-agent parallel execution with independent worktrees
- Project-level long-term memory: user profiles, project facts, experiences, SOPs, and proactive queries
- MCP Server, Skills, Hooks, and local plugin extensions
- Four permission modes with optional bubblewrap sandbox
## Quick Start
Environment requirements: Linux, Python 3.12+, [uv](https://docs.astral.sh/uv/). bubblewrap is optional.
Install the command-line tool from PyPI:
```bash
uv tool install windcode
windcode /path/to/project
```
Alternatively, install to the current Python environment:
```bash
uv pip install windcode
```
Run from source:
```bash
uv sync --frozen --all-groups
cp .windcode/config.toml.example .windcode/config.toml
uv run windcode /path/to/project
```
Minimum model configuration:
```toml
primary_provider = "primary"
[providers.primary]
protocol = "openai_compatible"
model = "your-model"
base_url = "https://example.com/v1"
api_key_env = "MODEL_API_KEY"
```
Keys should be provided through environment variables or Windcode credential storage, not written to project configuration.
```bash
export MODEL_API_KEY="..."
uv run windcode .
```
Common startup parameters:
```text
--config FILE
--model PROVIDER_OR_MODEL
--resume SESSION_ID
--permission-mode plan|default|accept_edits|full_access
--sandbox / --no-sandbox
```
## Common Commands
```text
/new New session
/resume [SESSION_ID] Resume session
/history View history nodes
/rewind RECORD_ID Rewind to history record
/model Manage models and providers
/mode MODE Switch permission modes
/memory Manage long-term memory
/extensions Manage extensions
/compact Compact current context
/agents View sub-agents
/status View running status
```
## MCP Server
```toml
[extensions]
enabled = true
[extensions.mcp_servers.example]
transport = "streamable_http"
url = "https://example.com/mcp"
enable = true
required = false
```
Servers with `enable = false` will not connect, participate in tool search, or inject model context. `required` only applies when the server is enabled, indicating that it must connect successfully during startup.
## Local State
Windcode stores memory, sessions, traces, extension state, and worktrees under a selected state root:
```toml
[storage]
project_state_root = ".windcode/state"
user_storage_root = "~/.local/state/windcode/state"
```
When configuring the project state root, prioritize the project directory; if not configured, use the user state directory. `.windcode/config.toml` and `.windcode/state/` should not be committed to Git.
## Development
```bash
uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest -q
uv build
```
## Building and Publishing
Update the version number in `pyproject.toml` and `src/windcode/__init__.py` before release, and complete the full checks:
```bash
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
```
Publish to TestPyPI for verification:
```bash
uv publish \
--publish-url https://test.pypi.org/legacy/ \
--token "$TEST_PYPI_TOKEN"
```
Official releases are published automatically through GitHub Release: create a tag matching the project version, e.g., `v0.1.0`, and then publish the GitHub Release. `.github/workflows/publish.yml` will verify the tag, run tests, build the distribution package, and publish using PyPI Trusted Publishing. Configure the following Trusted Publisher on PyPI before the first release:
```text
Owner: tingfeng347
Repository: windcode
Workflow: publish.yml
Environment: pypi
```
PyPI does not allow overwriting already published versions with the same name; increment the version number before republishing.
Production code is located in `src/windcode/`. Local `tests/` and `spec/` directories are ignored by Git and used only for development and specification management.
## License
[Apache-2.0](LICENSE)
