peforth is an AI-first Forth environment hosted by Python. It combines a small extensible Forth kernel, direct access to Python, and an optional AI-assisted terminal REPL in the single f command.
Version 2 is now the mainline implementation on master. The migration from v1 has been completed; the previous migration branch is no longer required for installation.
code ... end-code. Use Python libraries without a separate foreign-function runtime.forth and chat modes.peforth/f/; host runtime and integrations live in peforth/*.py.Compatibility: peforth v2 is a major rewrite, not a drop-in replacement for v1. Legacy features such as the v1 debugger, Jupyter integration, and
peforth.ok()are not supported. Use the v1.33 release if your application depends on those interfaces.
The development installation is sourced from this repository; it is not presented here as a published PyPI release.
Windows and Ubuntu/WSL should use separate checkouts and virtual environments.
git clone https://github.com/hcchengithub/peforth.git ~/.peforth
cd ~/.peforth
uv venv
uv pip install -e .
~/.peforth/.venv/bin/f
To invoke f by name from other directories in the current shell:
export PATH="$HOME/.peforth/.venv/bin:$PATH"
f
For WSL, keep this Linux checkout inside its Linux filesystem (for example, ~/.peforth), not under /mnt/c.
git clone https://github.com/hcchengithub/peforth.git "$HOME\.peforth"
Set-Location "$HOME\.peforth"
uv venv
uv pip install -e .
& "$HOME\.peforth\.venv\Scripts\f.exe"
To invoke f by name from other directories in the current PowerShell session:
$env:PATH = "$HOME\.peforth\.venv\Scripts;$env:PATH"
f
If uv reports invalid peer certificate: UnknownIssuer on a managed Windows network, use native Windows certificate handling:
uv --native-tls pip install -e .
Do not disable TLS certificate verification.
Start f and enter ordinary Forth:
1 2 + . cr
: square dup * ;
5 square . cr
words
Define a Forth word directly in Python:
code double
vm.push(vm.pop() * 2)
end-code
21 double . cr
The host Python code runs in the same process as the Forth VM, so it has the normal permissions of your local user account.
To leave the REPL, enter bye or press Ctrl-D. For Forth definitions, introspection, parsing, control structures, and more Python integration examples, see peforth manual（漂亮字） and peforth manual (English).
Set OPENAI_API_KEY in the process environment or in ~/.peforth/.env (Windows: $HOME\.peforth\.env). Keep it private and never commit it.
Example local configuration:
OPENAI_API_KEY=your-platform-api-key
# Set this to a model supported by your API project:
# PEFORTH_AI_MODEL=your-model-id
PEFORTH_AI_SKILLS_DIR=skills
Inside the REPL:
ai: Explain what a Forth defining word is.
chat
In chat mode, subsequent input goes to the selected AI session. Enter forth to return to Forth mode. Other commands include ai-status, ai-sessions, ai-new, and ai-confirm.
Local execution is permissioned: When the assistant proposes Forth code via peforth_run_forth, peforth asks for approval. You can approve once, trust only the current AI task, deny, or cancel. Approved code executes in the live local VM and can use its Python bridge; review proposals before approving them. See AI support for details about approvals, sessions, configuration, and troubleshooting.
AI API usage is optional and billed according to your OpenAI Platform account and selected model.
| Location | Purpose |
|---|---|
peforth/projectk.py |
Core Forth VM and Task execution |
peforth/f/base.f |
Base vocabulary, defining words, and compiler-level constructs |
peforth/f/auxiliary.f |
Auxiliary Forth words |
peforth/f/ai.f |
Forth-facing AI words and control flow |
peforth/repl.py |
Terminal REPL and runtime initialization |
peforth/ai_bridge.py, peforth/ai_tools.py |
AI transport, session helpers, and host tools |
docs/ |
User manual, AI guide, design documents, and historical migration plan |
skills/, plugins/ |
Repository-owned AI skill and plugin assets |
tests/ |
Automated tests |
The skills/ and plugins/ source directories are not automatically installed into external AI CLIs.
This is an editable source checkout. To update, inspect your local changes and pull from master:
cd ~/.peforth
git status
git pull --ff-only
uv pip install -e .
Run the test suite from the checkout using your environment’s Python; for example:
.venv/bin/python -m unittest discover -s tests
On Windows, use .venv\Scripts\python.exe instead.
Do not run git pull over uncommitted modifications without reviewing them first. The historical V2 migration plan is retained as background, not as the current installation guide.