Skip to content

Commit 8b474f2

Browse files
ab-10ab-10
authored
Add install instructions for spx (#16)
1 parent 2442a9a commit 8b474f2

3 files changed

Lines changed: 179 additions & 28 deletions

File tree

‎docs/spx/index.mdx‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
---
2+
title: spx
3+
---
4+
5+
spx enables you to define, run, and modify complex backend systems using only markdown specifications.
6+
7+
:::warning Early Preview
8+
spx is still rough around the edges.
9+
We'd love your feedback on how the spx development workflow compares to yours.
10+
11+
Hit us up on [Discord](https://discord.gg/n3SsVDAW6U) or email me on armin (at) recurse (dot) ml.
12+
:::
13+
14+
## Prerequisites
15+
16+
Before using spx, ensure you have:
17+
18+
- Claude Code CLI installed and available as `claude`.
19+
- Runtime for your chosen implementation language (Python, TypeScript, or Rust).
20+
spx uses these languages as intermediary representations (IRs) to generate your actual implementation code.
21+
22+
## Quickstart
23+
24+
### 1. Download the spx Binary
25+
26+
Download the appropriate binary for your system architecture:
27+
28+
- **Linux x64:** [linux-x64](https://storage.googleapis.com/docs-recurse-ml/spx/spx-darwin-x64/spx)
29+
- **Linux ARM64:** [linux-arm64](https://storage.googleapis.com/docs-recurse-ml/spx/spx-linux-arm64/spx)
30+
- **Linux x64 (musl):** [linux-x64-musl](https://storage.googleapis.com/docs-recurse-ml/spx/spx-linux-x64-musl/spx)
31+
- **Linux ARM64 (musl):** [linux-arm64-musl](https://storage.googleapis.com/docs-recurse-ml/spx/spx-linux-arm64-musl/spx)
32+
- **macOS Intel (x64):** [darwin-x64](https://storage.googleapis.com/docs-recurse-ml/spx/spx-darwin-x64/spx)
33+
- **macOS Apple Silicon (ARM64):** [darwin-arm64](https://storage.googleapis.com/docs-recurse-ml/spx/spx-darwin-arm64/spx)
34+
- **Windows x64:** [windows-x64](https://storage.googleapis.com/docs-recurse-ml/spx/spx-windows-x64/spx.exe)
35+
36+
**Troubleshooting:**
37+
1. If using MacOS Rosetta, download the binary for `darwin-arm64`.
38+
39+
40+
**Adding to your PATH:**
41+
42+
After downloading, make the binary executable and add it to your PATH:
43+
```bash
44+
# Linux/macOS
45+
chmod +x spx
46+
sudo mv spx /usr/local/bin/
47+
48+
# Or add to your user bin directory (no sudo required)
49+
mkdir -p ~/.local/bin
50+
mv spx ~/.local/bin/
51+
# Add to your shell config: export PATH="$HOME/.local/bin:$PATH"
52+
```
53+
54+
```powershell
55+
# Windows (PowerShell as Administrator)
56+
# Move spx.exe to a directory like C:\Program Files\spx\
57+
# Add that directory to your PATH environment variable
58+
```
59+
60+
Verify installation:
61+
```bash
62+
spx --version
63+
```
64+
65+
### 2. Create a New Project
66+
67+
Navigate to where you want your project and create a new directory:
68+
```bash
69+
mkdir my-spx-project
70+
cd my-spx-project
71+
spx init
72+
```
73+
74+
This initializes a new spx project with the following structure:
75+
```
76+
my-spx-project/
77+
├── specs/ # Your markdown specifications go here
78+
│ └── example.md # Starter example spec
79+
├── .spx/ # Internal spx metadata (don't edit)
80+
│ └── prev_specs/ # Tracks changes between generations
81+
├── out/ # Generated code appears here (auto-created on first gen)
82+
└── .gitignore # Pre-configured to ignore generated files
83+
```
84+
85+
**What each directory does:**
86+
87+
- **`specs/`** - Where you write your system specifications in markdown. All `.md` files here are read by spx.
88+
- **`.spx/`** - Internal tracking data used by spx to detect changes and optimize generation.
89+
- **`out/`** - Contains generated implementation code. You can read this to understand what was generated, but don't edit it directly - changes will be overwritten.
90+
91+
### 3. Build!
92+
93+
#### Define Specs
94+
95+
Create or edit markdown files in `specs/`.
96+
spx reads all `.md` files in the `specs/` directory and treats them as the specification for your system.
97+
98+
Principles for writing effective specs:
99+
100+
1. **Be specific about end-user behavior:** clearly define the interfaces (whether CLI or API endpoints) that are exposed to your users.
101+
2. **Managing granularity:**
102+
you're in control of the level of granularity at which you want to work at.
103+
For example, if the database engine and schema is important to your design, you should specify them.
104+
But if they're not, then LLM will likely make a reasonable guess.
105+
3. **Out of scope:** explicitly state what's out of scope for now and the limitations you're fine with at the current stage.
106+
107+
108+
#### `spx gen`
109+
110+
Once your spec is ready, generate the code:
111+
```bash
112+
spx gen
113+
```
114+
115+
This command:
116+
- Reads all markdown files from `specs/`
117+
- Compares them with the previous generation (if any)
118+
- Uses Claude Code CLI to generate or update code in `out/`
119+
- Creates/updates `out/build.sh` and `out/run.sh` scripts
120+
121+
**First time:** Generates everything from scratch.
122+
123+
**Subsequent runs:** Only updates what changed in your specs, preserving what still matches.
124+
125+
#### `spx build
126+
127+
- Sets up language-specific environments (virtualenv for Python, npm install for TypeScript, etc.)
128+
- Installs required libraries
129+
- Compiles code if necessary (e.g., for Rust or TypeScript)
130+
131+
#### `spx run`
132+
133+
Executes your generated system.
134+
Any arguments you pass to `spx run` are forwarded to your application's entry point.
135+
136+
#### Iterate
137+
138+
As you develop, update your specs in `specs/` and repeat the cycle.
139+
spx tracks what changed and only updates relevant parts of your implementation.
140+
141+
## How It Works
142+
143+
spx is a programming language that uses traditional languages (Python, TypeScript, Rust) as intermediary representations.
144+
You control your system architecture and behavior through specs, not by writing implementation code directly.
145+
146+
## Commands Reference
147+
148+
- `spx init` - Initialize a new spx project
149+
- `spx gen` - Generate/update implementation code from specs
150+
- `spx build` - Build the generated code and install dependencies
151+
- `spx run [args]` - Execute your system (forwards args to your application)
152+
- `spx clean` - Remove all generated code and build artifacts
153+
154+
## Best Use Cases
155+
156+
spx works best for:
157+
158+
- **Web backends and APIs** - REST/GraphQL servers, microservices
159+
- **CLI tools and scripts** - Command-line utilities, automation scripts
160+
- **ML pipelines** - Training scripts, data processing, inference servers
161+
162+
spx is designed for non-visual backend systems. For applications with significant UI components, traditional development approaches may be more suitable.
163+
164+
## Getting Help
165+
166+
- **Discord:** [Join our community](https://discord.gg/n3SsVDAW6U)
167+
- **Email:** armin (at) recurse (dot) ml
168+
- **Issues:** Share bugs, unexpected behavior, or cases where spec-level fixes weren't sufficient
169+
170+
Your feedback directly shapes spx development!

‎docusaurus.config.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,15 @@ const config: Config = {
5757
sidebarPath: './sidebars.ts',
5858
lastVersion: 'current',
5959
}],
60+
[
61+
'@docusaurus/plugin-content-docs',
62+
{
63+
id: 'spx',
64+
path: 'docs/spx',
65+
routeBasePath: 'spx',
66+
sidebarPath: false,
67+
lastVersion: 'current',
68+
}],
6069

6170
],
6271
presets: [

0 commit comments

Comments
 (0)