# Sillok
Sillok is a Rust CLI for meticulous agentic work chronicles. It records daily
objectives, completed tasks, corrections, and retractions into a structured
archive instead of a fragile append-only text log.
The name comes from Korean `sillok`, the court chronicles of Joseon. The design
goal is similar: keep precise records of what happened, when, under what
objective, and in what working context.
## Status
Sillok is an early local-first CLI. The command interface is intended to be
stable enough for agent harnesses, but the serialized archive format is private
and may change.
## Install
Build the binary in dev mode:
```bash
cargo build
```
Install it onto your PATH:
```bash
cargo install --path .
```
Then use:
```bash
sillok --help
```
## Storage
By default, Sillok stores one user-global archive at:
```text
$XDG_DATA_HOME/sillok/sillok.slk.zst
```
If `XDG_DATA_HOME` is unset, it falls back to:
```text
~/.local/share/sillok/sillok.slk.zst
```
Override the store with either:
```bash
sillok --store /path/to/sillok.slk.zst day
SILLOK_STORE=/path/to/sillok.slk.zst sillok day
```
The current implementation persists a compressed private archive. On every
mutation, it loads the archive, builds indexed in-memory state, validates the
change, appends events, and atomically rewrites the archive.
## Output
JSON is the default output and is intended for agents:
```json
{
"ok": true,
"command": "note",
"ids": {},
"data": {},
"warnings": []
}
```
Use `--human` for short interactive summaries:
```bash
sillok --human day
```
## Daily Workflow
Initialize explicitly, or let the first write initialize the archive:
```bash
sillok init
```
Add an objective for the day:
```bash
sillok objective add "Finish archive indexing"
```
Record a completed task:
```bash
sillok note "Implemented timerange query indexing" --tags rust,sillok
```
Attach a note under an objective by passing the objective id as the parent:
```bash
sillok note "Split reducer from view indexing" --parent <objective_id> --tags rust,sillok
```
Complete the objective:
```bash
sillok objective complete <objective_id> --note "All scoped work is complete"
```
Read today:
```bash
sillok day
```
Read a specific day:
```bash
sillok day --date 2026-05-13
```
Query a timerange:
```bash
sillok query --from 2026-05-13T00:00:00 --to 2026-05-13T23:59:59
```
## Corrections
Amend current derived state:
```bash
sillok amend <record_id> --text "Corrected task text"
sillok amend <record_id> --status completed
sillok amend <record_id> --purpose "Clarify why this work mattered"
sillok amend <record_id> --tags rust,indexing
```
Retract a task or objective from current views:
```bash
sillok retract <record_id> --reason "Recorded against the wrong objective"
```
Show current state and event history for one record:
```bash
sillok show <record_id>
```
Render a tree:
```bash
sillok tree --root <record_id>
sillok tree --date 2026-05-13
```
## Backfill And Timezones
Use `--at` to record when work occurred, and `--tz` to choose day attribution
for naive timestamps:
```bash
sillok --tz Asia/Seoul --at 2026-05-13T21:30:00 note "Backfilled a late task"
```
RFC3339 timestamps keep their offset:
```bash
sillok --at 2026-05-13T21:30:00+09:00 note "Backfilled a Seoul-time task"
```
## Maintenance
Validate the archive:
```bash
sillok doctor
```
Export current records as JSON:
```bash
sillok export json
sillok export json --from 2026-05-13T00:00:00 --to 2026-05-13T23:59:59
```
Reset the whole archive. This creates a timestamped backup first:
```bash
sillok truncate --yes
```
## Development
Run checks:
```bash
cargo fmt
cargo clippy --all-targets --all-features
cargo test
```
Project constraints:
- No `unwrap()` or `expect()` in project source or tests.
- Keep modules under 300 lines where practical.
- Keep folder `mod.rs` files to module declarations only.
- Prefer explicit error handling and structured tracing.
- Do not treat the serialized archive as a public standard; optimize the
in-memory representation and CLI behavior first.
## Design Notes
See [docs/plan/sillok-cli-chronicle-design.md](docs/plan/sillok-cli-chronicle-design.md)
for the initial implementation plan and data model notes.