calcit.cirru is the primary source snapshot; legacy compact.cirru is still compatible
CLI-first development with calcit and caps, designed to work well with AI agents in terminal workflows
Better CLI editing and validation for CI, docs lookup, module management, and incremental updates

Install

Build and install with Rust:

# get Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# get Calcit user-facing tools
cargo install calcit --bin calcit --bin caps

Installed binaries:

calcit, the runtime and JS compiler
caps, for downloading dependencies declared in deps.cirru

When installing from source, install the same public tools:

cargo install --path . --bin calcit --bin caps

For new GitHub Actions workflows, use setup-calcit@v1. It installs calcit and creates a lightweight cr -> calcit compatibility link for existing workflow commands; for pre-rename releases it falls back to cr and exposes the equivalent calcit command. Local installations ship only calcit; migrate local scripts directly instead of relying on a wrapper. Existing setup-cr workflow tags remain supported.

Quick Start

Evaluate snippets:

calcit eval 'range 100'

calcit eval 'thread-first 100 range (map $ \ * % %)'

Run with a runtime snapshot such as calcit.cirru (legacy filename: compact.cirru):

calcit calcit.cirru # run once (default)
calcit compact.cirru # legacy filename still works

calcit # by default, it picks `calcit.cirru`, then falls back to `compact.cirru`

calcit -w # watch mode (explicit flag required)

By default Calcit reads :init-fn and :reload-fn from calcit.cirru configs (falling back to compact.cirru). You may also specify functions:

calcit --init-fn='app.main/main!' --reload-fn='app.main/reload!'

You may also configure :entries in calcit.cirru:

calcit --entry server

JavaScript codegen

Calcit compiles to JavaScript with consistent semantics. In browser or Node projects, JavaScript interop is still expected.

calcit js # compile to js, also picks `calcit.cirru` by default
calcit js --emit-path=out/ # compile to js and save in `out/`

By default, js code is generated to js-out/. You will need Vite or Node to run it, from an entry file:

import { main_$x_, reload_$x_ } from "./js-out/app.main.mjs";
main_$x_(); // which corresponds to `main!` function in calcit

CLI and Agent Workflow

The recommended workflow is plain text editing plus CLI validation, often driven by an AI agent in terminal.

Common commands:

calcit docs agents --full   # read the current agent workflow guide
calcit query search 'foo'   # locate code by symbol or string
calcit edit ...             # structured edits for defs, imports, config, modules
calcit js                   # compile once
calcit js -w                # watch mode
caps                    # install/update dependencies from deps.cirru

Calcit Editor is no longer the recommended path for everyday development. If you still need the older editor workflow, see Calcit Editor.

Related examples and workflows:

Minimal Calcit
Respo Calcit Workflow
setup-calcit for new GitHub Actions workflows

Modules

deps.cirru declares dependencies that need to download, which correspond to repositories on GitHub. Specify a branch or a tag:

{} (:calcit-version |0.9.11)
  :dependencies $ {} (|calcit-lang/memof |0.0.11) (|calcit-lang/lilac |main)
  :dev-dependencies $ {} (|calcit-lang/calcit-test |0.1.0)

Run caps to resolve the recursive dependency graph and install it. Immutable revisions are stored under ~/.config/calcit/module-caches/, while the current project receives links under .calcit/modules/. Different projects can therefore use different revisions without switching a shared checkout. Existing project module links are the only runtime source for package-style module paths; explicit relative and absolute paths retain their normal direct resolution.

Published SemVer tags are preferred. Branch refs remain supported for development, but caps warns with the resolved commit. When a graph requests several SemVer tags for one repository, the highest requested version is selected and reported.

Root projects install both :dependencies and :dev-dependencies. Recursive resolution only follows :dependencies, so test and maintenance modules declared by a dependency do not leak into consumers. Use caps add --dev <org/repo>@<ref> and caps remove --dev <org/repo> to manage the development group.

:calcit-version helps with version checks and provides hints in CI.

To load modules, use :modules configuration and the runtime snapshot file calcit.cirru (legacy: compact.cirru):

:entries $ {}
  :default $ {}
    :modules $ [] |memof/calcit.cirru |lilac/

Paths defined in :modules load from the snapshot directory's .calcit/modules/, e.g. .calcit/modules/memof/calcit.cirru. Run caps to materialize or refresh that project-local view.

Modules ending with / are automatically suffixed with calcit.cirru, and still fall back to compact.cirru for compatibility.

Inspect and verify the resolved graph with:

caps tree
caps why calcit-lang/memof
caps status
caps verify

Development

Local validation commands:

# run tests in Rust
cargo run --bin calcit -- calcit/test.cirru

# run tests in Node.js
cargo run --bin calcit -- calcit/test.cirru js && yarn try-js

# run snippet
cargo run --bin calcit -- eval 'range 100'

# internal compiler/WASM validation when working on this repository
cargo run --bin calcit -- calcit/test.cirru ir
yarn try-wasm

For repository development, the usual validation flow is:

cargo fmt
cargo clippy -- -D warnings
yarn compile
cargo test
yarn check-all

Cirru Parser for indentation-based syntax parsing.
Cirru EDN for runtime snapshot file parsing (calcit.cirru / legacy compact.cirru).
Ternary Tree for immutable list data structure.

Other tools:

Error Viewer for displaying .calcit/error.cirru
IR Viewer for rendering program-ir.cirru

Some resources:

Dev Logs https://github.com/calcit-lang/calcit/discussions
视频记录 https://space.bilibili.com/14227306/channel/seriesdetail?sid=281171

License

MIT