orkmode/AGENTS.md

Agent Guidelines

Instructions for AI agents working on orkmode.

Project Context

Orkmode is a native org-mode implementation: Rust parser/core + Qt/QML UI.

Current state: v0.1 — parser and CLI complete, no UI yet.

Codebase Structure

crates/
├── org-ast/        # AST types (Document, Section, Element, etc.)
├── org-parser/     # Tree-sitter parser, AST conversion
├── ork-server/     # 9P server exposing org files (bin: ork-server)
└── ork-cli/        # CLI tool, a 9P client (bin name: ork)

Working with the Code

Build

cargo build --release

Requires: Rust 1.70+, C compiler (for tree-sitter grammar).

Test

cargo test

CLI

The ork CLI operates on directories by default:

ork info .                    # Aggregate info for all .org files
ork sections --todos-only     # List TODOs across files
ork query "tag:work" -R       # Recursive search
ork get "section-id" -j       # JSON output
ork toggle "task-id" -n       # Dry run
ork add "New Task" file.org --todo TODO

Use -j/--json for machine-readable output. Use -n/--dry-run for mutations.

Architecture Decisions

Parser

• Uses tree-sitter-org grammar (git submodule)
• Pinned to tree-sitter 0.22 (0.23+ requires rustc 1.90+)
• Conversion in org-parser/src/convert.rs maps tree-sitter nodes to AST

AST

• Follows org-element spec
• All nodes have Span for source locations
• Document → Section* → Element* / Section*
• Inline objects (bold, links) are partially implemented

9P server

• ork-server exposes org files as a 9P namespace (docs, sections, fields, agenda, query)
• Structural ops via the ctl file: rm, move, promote, demote, refile, archive, lint
• ork is a pure 9P client; all org logic lives in the server

Conventions

Rust

• Edition 2021
• Use thiserror for error types
• Use serde for serialization
• Prefer &str over String in function signatures
• Match existing code style

Commits

• Imperative mood: "Add feature" not "Added feature"
• Reference issue/context in body if relevant

CLI

• Commands operate on paths (file or directory)
• Default to current directory
• -R for recursive
• -j for JSON output
• -n for dry run

Current Limitations

1. Inline objects incomplete — tree-sitter-org doesn't fully parse bold/italic/links
2. Property/tag write commands — stubs only, not implemented
3. Timestamp text — displays "set" placeholder, not actual date
4. No incremental parsing — full reparse on every call

Next Steps (v0.3)

Priority: Qt/QML read-only document viewer, over 9P.

Tasks:

1. Set up Qt6/QML project in ui/
2. Connect to ork-server over 9P (no FFI)
3. Implement document model (QAbstractItemModel) from the 9P namespace
4. Basic headline rendering with folding
5. Structural styling (keywords, priorities, tags, timestamps)

Testing Changes

Before committing:

cargo build --release
cargo test
./target/release/ork check .
./target/release/ork info test.org -j

Questions?

Check VISION.md for project goals and design principles.