Hactar Docs

The preferred way to run hactar is via roswell. If you have it already do:

ros install hactar-project/hactar

If you don't have roswell yet install it or use the hactar script:

curl -L https://hactar.space/install.sh | bash

Nix:

nix profile install "github:hactar-project/hactar"hactar hactar.init

GitHub Releases:

Important: You'll need to run hactar hactar.init if you install without running install.sh or using roswell.

Now you can run hactar in any git repo:

hactar

You'll want to set API keys. Any of the following will do:

• OPENAI_API_KEY: The API key for OpenAI models

• ANTHROPIC_API_KEY: The API key for Anthropic models

• GEMINI_API_KEY: he API for vertex/google ai studio

• OPENROUTER_API_KEY: The OpenRouter api key.

You'll likely want to set a model you can do this with an environment variable HACTAR_MODEL. In this case a github_copilot model:

env HACTAR_MODEL="copilot/gemini-3.1-pro-preview" hactar

Hactar comes with a several different interfaces. The default is a minimal readline tui. If you want to use Hactar with ACP pass --acp. To disable all tui pass --in-editor and you will get a minimal Hactar designed to be wrapped in an editor like Neovim or Emacs. Pass --lit to use Hactar literately via org-mode.

Hactar is a Common LISP project. This makes it very hackable and you might want to run it from source.

First get all the dependencies. Mainly you will just need a working quicklisp environment. This is easiest on nix, you can use the shell.nix and flake.nix.

Arch:

sudo pacman -Sy git sbcl readline libuv rlwrap pkg-config openssl zlib libyaml libev libevdev

Ubuntu:

sudo apt updatesudo apt install git sbcl libreadline-dev libuv1-dev rlwrap pkg-config libssl-dev zlib1g-dev libyaml-dev libev-dev

Now you can run make build to get a build of it. The build script should download all the quicklisp dependencies for you.

Hactar will be built to ./bin/hactar. Please report any issues you run into and read the development guide.

Rules

Rules are how the system prompt is changed in response to code

Analyzers

Handle parsing code and extracting details like is-react?

Processors

Take user input and LLM output and do something with it

Slash Commands

Slash commands are the primary interactive mechanism in the Hactar REPL e.g /add for adding files

Dot Commands

Dot commands operate on the context/prompt itself. e.g .mod! to make code changes

Modes

how Hactar changes the behavior of commands based on context and environment

MCP

Model Context Protocol -- this the standard for tool calling that LLM providers have settled on.

ACP

Agent Context Protocol -- An extension of MCP for agents

Hactar is developed on GitHub and the primary route for help is via Discussions and Issues. You can also hop into the Discord and ask questions.

When reporting issues please include info like hactar version, model, settings etc. You can get all the info like version, model, context, settings etc with the /dump command.

Hactar extensions are simple lisp files that get copied into a folder. Similar to the extension system you find in Emacs or Neovim ecosystems.

To install one simply clone it onto your path somewhere (e.g "/.config/hactar/plugins") and add it to your hactar.lisp:

(load "myplugin/core.lisp")

You can manage your plugins using git. Here is an example make file to update all plugins:

PLUGINS_DIR ?= ~/.config/hactar/pluginsupdate-plugins:        @echo "Updating plugins in $(PLUGINS_DIR)..."        @for dir in $(PLUGINS_DIR)/*; do \                if [ -d "$$dir/.git" ]; then \                        echo "--> Updating $$dir"; \                        (cd "$$dir" && git pull); \                fi \        done        @echo "Done.".PHONY: update-plugins

Pass the --watch flag to hactar and then use the following syntax in comments

• AI!: Trigger hactar to make changes. Describe the changes in the comment line and following lines.

• AI?: Trigger hactar to anwser questions about the code.

Use the scan command hactar scan

You can pass the format flag to control what hactar outputs. For example, here is how to generate an org-mode file describing the API of the codebase:

hactar scan -f org-mode

Hactar has three model types:

• main/current/default model: This is the default model used for most tasks

• cheap-model: This is the model used for programmatic and architecture tasks. For example, to generate JSON meta data from documentation.

• embedding-model: The model used for embedding

You can list available models with:

/models

You can use an AGENTS.md, AGENTS.org, .hactar.guide.md, or .hactar.guide.org in the project's root. It will be added to context

In $XDG_CONFIG_DIR/hactar/models.yaml.

In $XDG_CONFIG_DIR/hactar/prompts.

Hactar accomplishes smart context using what we call modes. Modes work with specific filetypes and use old school techniques like parsing and regex to determine what your code is, what you are doing, and what context you might need. LISP allows us to build up this using a DSL. For example, want to check you are in a React project and then add React api docs? Just a good old call to a function is-project-react?.

Why not something like skills triggers? Or rules? The same reason we also eschew MCP, it keeps the context smaller. In other CLI tools automatic loading of e.g skills is accomplished by the LLM. This means you are constantly giving up context to listing out available skills, docs, etc. Not only are you giving up context but you are adding latency by requiring extra calls to an LLM.

Using actual code to add stuff to context allows us to load things into context without sacrifices.

You have three options for adding API docs:

1. Importing the docs file into the database with the /docs.import command. Note: They will ned to follow the API Format

2. With a defdoc macro.

3. Just adding the file with /add

The last is the most simple and for one off things just using /add is fine.

The most powerful route is the defdoc macro. You can define where the docs are in code and then use LISP and Hactar features to intelligently add an remove docs.

Here is an example of that:

(defdoc "Latest React Docs" :source "hactar:docsets/react.19.2.3.org" :version "latest")

If you want to for example listen to stack changes and dynamically add docs depending on what you are working on you can use hooks. Here is an example of that:

(defun update-stripe-docs (&rest args)  (declare (ignore args))  (defdoc "Stripe API Reference"    :source (cond              ((member "go" *stack* :test #'string=) "hactar:docsets/stripe.go.latest.org")              ((member "node" *stack* :test #'string=) "hactar:docsets/stripe.node.latest.org")              ((member "ruby" *stack* :test #'string=) "hactar:docsets/stripe.ruby.latest.org")              (t "hactar:docsets/stripe.curl.latest.org"))    :uri "stripe-api-docs"    :version "latest"))(nhooks:add-hook *stack-changed-hook* (make-instance 'nhooks:handler :fn #'update-stripe-docs :name 'stripe-docs-update))(update-stripe-docs)

Once you have docs in Hactar you can use /docs-add to search through them and add to context. Or you can write rules and hooks to add them automatically.

API docs can be in any format but if they are in org-mode and follow some conventions then Hactar can do things like slice up the API docs so only specific parts are added to context. This can be very useful for reducing token usage. See the docs for the API Format for more info.

Hactar has partial support for agent skills. We say partial because in Hactar you have to load agent skills manually. We do this intentionally to reduce token usage, increase model performance, and reduce LLM queries.

Load a skill into context using skills.load <name> [--forms] [--ref]. Add a skill using skills.add e.g hactar skills.add anthropics/skills skills.

Skills Commands:

skills.list                        - List available skillsskills.search                      - Search skills and load oneskills.load <name> [--forms] [--ref] - Load a skill into contextskills.add <source>                - Add a skill from a sourceskills.validate <path>             - Validate a skill directory or nameskills.doc [format]                - Generate documentation for available skillsskills.help                        - Show this help message

Pass the --acp flag to enable ACP mode.

• Ignore all of it with *.hactar

• Ignore context files with .hactar*.context.org

• Ignore port files with .hactar*.port

• Ignore transcripts with .hactar*.transcript.json

• Ignore session files with .hactar*.session.lisp

Hactar can be extended with rules. The simplest form of rules is just a file named .hactar.rules. This will be added to the context automatically.

This isn't particulary useful though. To make rules useful you need to have them triggered by something. Hactar provides a large variety of hooks and triggers for rules. Let's apply a rule when the project stack contains react:

(defrule :prefer-custom-hooks "Prefer custom hooks over libraries where possible." :triggers '(:stack (:react)))

Hactar is pretty good at extending itself. You can give rule generation a try with the /gen-rule command. Hactar will attempt to write a rule for based on your instructions. Then it will add it to your user.lisp file. Please read any rules it generates first and don't blindly accept them.

A core feature of Hactar is tight integration with a repository of reference docs. Most of the time documentation is automatically added to context as needed. You can manually add docs using /docs-add and you can drop docs from context using /docs-drop (or /drop).

/docs-add <source> -tags=js -covers=react

Hactar maintains a database of errors and solutions. You can import errors from org-mode files or add them manually.

Modes are how Hactar hard codes knowledge instead of relying on an LLM for every little thing. Modes let Hactar know how to look up API docs and tooling specific to the type of project you are working on. Hactar for example, can detect when a React project is being worked on then automatically add the React API docs and list of links to tutorials. A mode is a collection of prompts, analyzers, processors, hooks, and custom hardcoded dev tooling. Think LSP if it was developed in the LLM era.

You can manually enable and disable modes with /mode. You can list currently enabled modes with /modes.

Analyzers take code files an analyze them using a combination of hard coded and LLM models. By default they get enabled and disable automatically by modes.

Processors in Hactar handle processing the output from the LLMs.

For example here is the code that handles search and replace responses

(def-processor search-replace-processor (history)               "Parses and applies SEARCH/REPLACE blocks from the last assistant message."               (when history                 (let ((last-message (car (last history))))                   (when (string= (cdr (assoc :role last-message)) "assistant")                     (let* ((content (cdr (assoc :content last-message)))                            (blocks (parse-search-replace-blocks content)))                       (when blocks                         (format t "~&Applying ~A SEARCH/REPLACE block(s)...~%" (length blocks))                         (apply-search-replace-blocks blocks)                         (format t "~&Finished applying blocks.~%")))))))

Guides are READMEs for agents. A lot like Claude.md or AGENTS.md but in Hactar they are smart and hooked up to a knowledge repository. You can think of it like those developer guides for a stack. They cover everything from best practices, how to write tests for that specific stack, to API documentation.

Hactar doesn't just add these files to your context, it includes first class tooling for writing, editing, modifying, and slicing them up. It has special agent features and prompts to intelligently add and modify them.

You can add one to your current project by writing a AGENTS.md, AGENTS.org, .hactar.guide.org, .hactar.guide.md. By default it assumes you only want to load one and .hactar.guide will be prioritized.

The global XDG_CONFIG_DIR/hactar/.hactar.org will be loaded together with any project specific one.

Agents in hactar are instances of hactar that act on a task in a loop with REPL. For example, you might have a lint agent that automatically fixes lint issues.

Hactar comes wih several built in agents and is designed to make building new agents quick and easy. Often you can even have Hactar one shot generate you a new specific agent.

You run agents with the command /agent-run or agent.run. Agents are a simple function created using the defagent macro.

Example:

hactar agent.run cmd "bun run typecheck"

hactar agent.run cmd "bun run typecheck"

hactar agent.run test

[project.commands] test = "bun run test"

hactar agent.run typecheck

[project.commands] typecheck = "bun run typecheck"

hactar agent.run lint

[project.commands] lint = "bun run lint"

Hactar commands are divided into three types:

• slash commands. these are hactar commands and change the state of hactar e.g /add

• dot commands operate on the context and instruct the LLM. They might for example, create a new file.

• hactar sub commands. These are commands you pass to hactar on startup e.g create

/tool-call <tool_name> [key=value ...]

/tools

/tools-mode [prompt|api]

/permissions [clear|log|reset]

/allow <tool_name>

/deny <tool_name>

These variables can be set in your shell to configure Hactar's behavior.

• HACTAR_AUTHOR

  • Sets the author name for the project, used in generated content or commits.

  • Example: export HACTAR_AUTHOR="Your Name"

• HACTAR_CONFIG_PATH

  • Specifies the path to Hactar's configuration directory.

  • Default: ~/.config/hactar

  • Example: export HACTAR_CONFIG_PATH="/path/to/your/hactar_config_dir"

• HACTAR_DATA_PATH

  • Specifies the path to Hactar's data directory (starters, prompts etc)

  • Default: ~/.local/share/hactar

  • Example: export HACTAR_PATH="/path/to/your/hactar_data_directory"

• HACTAR_REPO_URL

  • Specifies the url to clone the hactar repo from. Use your own custom Hactar!

  • Default: git@github.com:hactar-project/hactar.git

• HACTAR_REPO_DIR:

  • The foloder where Hactar is cloned to

  • Default: ~/.local/share/hactar-repo

• PIPER_MODEL_PATH

  • The full path to the Piper TTS model file (e.g., .onnx). This is required for the assistant's audio features (--audio).

  • Default: ~/.config/hactar/speech/models/en_US-amy-low.onnx

  • Example: export PIPER_MODEL_PATH="/path/to/your/model.onnx"

• OPENAI_API_KEY: The API key for OpenAI models

• ANTHROPIC_API_KEY: The API key for Anthropic models

• GEMINI_API_KEY: The API for vertex/google ai studio

• OPENROUTER_API_KEY: The API keyA for open router

• HACTAR_DB_PATH: The path to the sqlite hactar database. Defaults to XDG_DATA_DIR/hactar/hactar.db

• AGENT_SAFE_ENV: Whether or not the environment is safe for running agents that might do things like delete files.Setting this to true or 1 will also enable --auto-cmds. Hactar will act on it's own and pontentially destroy systems. Please for the love of god don't enable this out of a VM.

• HACTAR_PRO_PATH: The path to content repository for pro features which by default is XDG_DATA_DIR/hactar/pro

• HACTAR_UTILS_PATH:

  • Specifies the directory where Hactar Pro utility scripts are symlinked. If this directory is in your shell's PATH, you can run scripts like scripts-list directly.

• HACTAR_SHELL:

  • The shell to use when running commands. Fallsback to $SHELL when not set and then to bash

• HACTAR_MODEL: The model to use. Defaults to ollama/qwen3:14b

• HACTAR_CHEAP_MODEL: The model used for cheap parsing tasks. Defaults to ollama/qwen3:14b

• HACTAR_EMBEDDING_MODEL: The model used for generating embeddings. Defaults to ollama/nomic-embed-text Note: Only ollama embedding API is currently supported.

• HACTAR_COMPLETION_MODEL: The model used for completion. Defaults to ollama/qwen3:14b

• HACTAR_DOCS_META_MODEL: The model used for generating the metadata for documentation. Defaults to the value of cheap-model.

• HACTAR_GUIDE_PATH: Path to a plaintext file to include in the context. Use it to override a AGENTS.md file or .hactar.guide.org in the project's root.

• HACTAR_TEMPLATE_SEARCH_PATHS Environment variable that sets *template-search-paths*. Provide a space-separated list of directory paths. Each path is converted to a directory pathname and used when resolving templates. Example: export HACTAR_TEMPLATE_SEARCH_PATHS="/home/user/templates /opt/shared/templates"

Project specific config can be placed in the current folder in a file name. .hactar.toml

[paths] database = "/home/user/dev/my-project/hactar.db" [project] author = "Your Name" language = "typescript" stack = ["react", "vite", "tailwind"] guide_extension = "md" guide_exclude_tags = ["nocontext", "ignore"] [project.commands] test = "npm test" lint = "npm run lint" [agent] safe_env = false [auto] lint = true test = true limits = 3 [[analyzers]] name = "package-json" enable = true [[analyzers]] name = "react-dependency" enable = true

[api_keys] openai = "sk-..." anthropic = "sk-ant-..." gemini = "..." openrouter = "sk-or-..."

You can customize anything in Hactar by using lisp. Hactar looks for this file at .hactar.user.lisp in the project root first, then at /.config/hactar/user.lisp.

• *debug* (Boolean)

  • Description: If t, enables verbose debug output.

  • Default: nil

• *git-autocommit* (Boolean)

  • Description: If t, Hactar will automatically create a git commit after applying changes from SEARCH/REPLACE blocks.

  • Default: t

• *http-port* (Integer)

  • Description: The port for the HTTP server, which provides API endpoints for integrations.

  • Default: 4269

• *mcp-port* (Integer)

  • Description: The port for the MCP server, which provides API endpoints for integrations.

  • Default: 4369

• *test-command* (String)

  • Description: The default command to run for the test watcher.

  • Default: "make test"

• *transcript-file* (String)

  • Description: The name of the file where the chat history transcript is saved.

  • Default: ".hactar.transcript.json"

• *shell* (String)

  • Description: The shell to use for running commands.

  • Default: "bash"

• *chat-history-limit* (Integer)

  • Description: The maximum character limit for the chat history before it is automatically compressed.

  • Default: 8000

• *multiline-mode* (Boolean)

  • Description: Toggles multiline input mode.

  • Default: nil

• *docs-folder* (String)

  • Description: The default folder to look for local documentation files when using /docs-add without arguments.

  • Default: "docs/"

• *max-content-chars* (Integer)

  • Description: Maximum character length for a file's content before it gets split (used by some internal functions).

  • Default: 30000

• *image-max-size-mb* (Integer)

  • Description: Maximum size in megabytes for an image file before a warning is issued.

  • Default: 1

• *guide-warn-chars* (Integer)

  • Description: Character limit for an active guide file's content before a warning is issued.

  • Default: 30000

• *guide-max-chars* (Integer)

  • Description: The hard character limit for an active guide file. If a file exceeds this, it cannot be activated.

  • Default: 100000

• *guide-file-extension* (String)

  • Description: The default file extension for guides generated with /guides-gen.

  • Default: "org"

• *guide-exclude-tags* (List of Strings)

  • Description: A list of tags to exclude headlines from the active guide file context.

  • Default: '("nocontext")

• *silent* (Boolean)

  • Description: If t, suppresses all non-essential output, including chat and model responses. Primarily used in execute mode when generating shell commands.

  • Default: nil

• in-editor: Boolean

  • Description: When T, indicates that Hactar is running inside an editor (e.g. Emacs, Vim). Set via the --in-editor CLI flag or the HACTAR_IN_EDITOR environment variable. When active, Hactar disables the curses-based TUI (falling back to simple numbered-list selectors), and redirects structured output to .hactar.{pid}.log in the repository root.

  • Default: nil

You can configure and add models in ~/.config/hactar/models.yaml.

Here is an example with all possible config values:

- name: anthropic/claude-3-7-sonnet-20250219 # the model namededit_format: diff # what edit format to use. defaults to diffmodel_name: claude-3-7 # short name for the modelextra_params: # extra stuff passed in http requests  extra_headers:    anthropic-beta: prompt-caching-2024-07-31,pdfs-2024-09-25max_output_tokens: 8192max_input_tokens: 80000cache_control: true # whether or not cache requestssupports: ["vision"] # an array of things the model supports

A few reasons:

• MCP eats up tokens fast

• It is extremely easy to decrease performance by including too many MCP servers.

Hactar is developed on GitHub and the primary route for help is via Discussions and Issues. You can also hop into the Discord and ask questions.

When reporting issues please include info like hactar version, model, settings etc. You can get all the info like version, model, context, settings etc with the /dump command.

Hactar is designed to not trip over other instances. You can launch a bunch of instances and get them running simultaneously.

That said, I discourage you from agent approaches to coding. You will be more productive by treating Hactar as a tool. What you are working on in your head is what Hactar should be working on. Use multiple instances more like workspaces to maintain diffferent context windows or even branches; but don't use them as agents. Like all LLMs tools Hactar can get stuck and just keep banging against a wall and not making progress while it eats up tokens. Hactar is meant to augment you.

org-mode has built in support and standards for literate workflows. In markdown literate features are tacked on. We rely on things like src-blocks for adding and removing files from context.

• Use hactar check to make sure everything is good in your enviroment.

• Read the error messages

The biggest way to avoid file editing issues is to use a SOTA model. As of July 2025, most of the big models tend to handle diff blocks with a 95%+ accuracy. Other models can struggle more.

When you encounter a block that cant be applied often the simplest solution is to just retry it. You can do this with /retry. If you are using a model that frequently needs retries you can set auto-retry to true and even increase retry-limit.

By default this is set to off because in my experience bad edits now tend to be caused by overly complex context windows. You often cant the get model to fix a mistake with a retry loop. You need to start it over.

• Use /drop to drop files

• Use /clear to drop all files and clear history

• Use /reset to return all settings to what they were when you booted hactar.

Occassionally you will get errors from an API provider. If trying again doesn't resolve the issue the first step is to check that provider works with hactar. You can use the -p flag to execute a single prompt and return a response:

hactar -m "provider/modelname" -e "Write hello world"

Run hactar pro.check to check for any issues with hactar pro.

If you are having issues with any of the content or extensions from the pro version of hactar, please email me or ping me on the discord.

Hactar was built in LISP so that we can enable quick extensibility and a large variety of workflows. Hactar is a tool that you can build on while building. An OS for your LLM.

You can use Hactar as a library to make scripts.

#!/usr/bin/env bashset -euo pipefailLISP=$1NAME=$(basename "$1" .lisp)shiftsbcl --load "$LISP" \    --eval "(sb-ext:save-lisp-and-die \"$NAME\"              :executable t              :compression t              :save-runtime-options t              :toplevel '$NAME:toplevel)"

# Find all Lisp files in src/bin/binsrcs := $(wildcard src/bin/*.lisp)binnames := $(basename $(notdir $(binsrcs))).PHONY: all clean $(binnames)all: $(binnames)$(binnames): %: bin/%bin/%: src/bin/%.lisp Makefile        mkdir -p bin        $(eval fullpath := $(shell pwd)/$<)        build-bin-sbcl $(fullpath) $(@F)        mv $(@F) bin/clean:        rm -rf bin

(eval-when (:compile-toplevel :load-toplevel :execute)  (ql:quickload '(:hactar :llm :adopt :uiop :str) :silent t))(defpackage :spell-check  (:use :cl)  (:export :toplevel))(in-package :spell-check)(defparameter *ui*  (adopt:make-interface    :name "spell-check"    :usage "spell-check [OPTIONS] FOLDER"    :summary "Spell check markdown files using LLMs."    :help "Spell checks all markdown files in FOLDER."    :contents (list               (adopt:make-option 'help                                  :help "Display help and exit."                                  :long "help"                                  :short #\h                                  :reduce (constantly t))               (adopt:make-option 'model                                  :help "Model to use (default: copilot/gpt-5-mini)"                                  :long "model"                                  :short #\m                                  :parameter "MODEL"                                  :initial-value "copilot/gpt-5-mini"                                  :reduce #'adopt:last))))(defun process-file (file model)  (format t "Processing ~A...~%" file)  (let* ((content (uiop:read-file-string file))         (word-count (length (str:words content))))    (if (> word-count 50000)        (format t "Skipping ~A: Word count ~D exceeds limit of 50000.~%" file word-count)        (let* ((prompt (format nil "Fix spelling and grammar. Return ONLY corrected content. Maintain formatting.~%~%CONTENT:~%~A" content))               (provider (intern (string-upcase (first (str:split "/" model))) :keyword))               (model-name (second (str:split "/" model))))          (multiple-value-bind (response tool-calls history)              (llm:complete provider                                     `(((:role . "user") (:content . ,prompt)))                                    :model model-name                                    :stream nil)            (declare (ignore tool-calls history))            (when response              (with-open-file (stream file :direction :output :if-exists :supersede)                (write-string response stream))              (format t "Updated ~A~%" file)))))))(defun run (folder model)  (let ((files (directory (merge-pathnames "**/*.md" (uiop:ensure-directory-pathname folder)))))    (format t "the files ~A~%" files)    (if files        (dolist (file files)          (process-file file model))        (format t "No markdown files found in ~A~%" folder))    ))(defun toplevel ()  (handler-case      (multiple-value-bind (arguments options) (adopt:parse-options-or-exit *ui*)        (when (gethash 'help options)          (adopt:print-help-and-exit *ui*))        (when (null arguments)          (format t "Error: FOLDER argument required.~%")          (adopt:print-help-and-exit *ui* :stream *error-output* :exit-code 1))        (run (first arguments) (gethash 'model options)))    (error (c)      (adopt:print-error-and-exit c))))

(push #P"/home/k/quicklisp/dists/quicklisp/software/" asdf:*central-registry*)(push (merge-pathnames "code/k2052/hactar/" (user-homedir-pathname)) asdf:*central-registry*)

make spell-check./bin/spell-check ./docs

Context engineering is the new and cool thing for working with LLMs. So many of the distinguishing features between AI tools is how they manage context. Some tools emphasize you managing the context with commands, some do it automatically, some do it with etc.

In Hactar we dramatically simplify the context engineering by simply using a plain org-mode file. Want to add a file? You can just insert it. Want to operate on your prompt using e.g grep? It is just a plain file so it just works. And all the agent automatic managing of context can be done through the same file as the context API. A single file is simpler for both humans and machines.

You start by enabling context files with the --context-expose flag:

hactar --context-expose

This will expose a context file to your current folder at .hactar.{pid}.context.org. This context file is the source of truth for context. It contains what is passed to the LLM.

Now you can add and drop files. You can do this by both editing the file and using hactar commands.

Using a command:

/add  main.lisp

Will insert a src block into .hactar.{pid}.context.org. You'll get something like this:

* Files ** main.lisp #+begin_src lisp :tangle "main.lisp" ; main.lisp source here #+end_src

You can re-organize. create headlines, link to src files, copy and paste documentation etc. Hactar relies solely the filename and paths (that tangle part) to determine files in context. Hactar fully understands org-mode and work with whatever you throw at it. Edit and write however you like and the changes will be synced back and forth.

/add  main.lisp

* Files ** main.lisp #+begin_src lisp :tangle "main.lisp" ; main.lisp source here #+end_src

/add npm:react@19.2.0

* Files * API Docs ** React :PROPERTIES: :VERSION:  19.2.0 :END: An org-mode version of the React API docs here

Hactar is unique in that it has tight integration with starter kits. The create command is sort of a universal create-react-app for a huge variety of stacks.

By default you just provide some details and then Hactar will use RAG to retrieve matching starter kits and ask you some generated questions.

1. Create the app

hactar create "A chess app. Use react-router and modern stack that can be deployed to cloudflare workers"

1. Select a starter kit

You will be presented first with a starter kit selection.

1. run scripts

Hactar will generate documentation and scripts for you. All Hactar apps come with a standard set of start,dev,test,lint,deploy. If you have direnv setup in your shell these will be automatically symlinked for you and you can run them with start, test etc. If not use ./scripts/start.sh.

1. Read and Use the Docs

Checkout the README.md and the .hactar.guide.org for the developer guide to your new codebase. If you are on Emacs the org file links will point to docs in the Hactar content repo. An app with complete books, API references, and tutorials right from the get go!

Hactar pro comes with a suite of scripts that all work together to provide little usability improvements.

• You can install them with hactar utils.install

  • to install all use: hactar utils.install all

• List them with: hactar utils.list

They get symlinked into a folder configured as HACTAR_UTILS_PATH. If you add this folder to your path you can do things like: scripts-list to select a script in any hactar project and run it.

Hactar is as good as any SOTA CLI tool at mapping and documentating a codebase.

1. Navigate to the codasbe cd path/to/project

2. Start hactar hactar

3. Scan the codebase hactar scan. This will usually take 30ish seconds. If longer please report because my goal is for it to always be fast as possible.

4. Ask questions "give me a high level overview of the codebase"

5. Ask how to build a specific part "how would I add a route for viewing chess games on a board given a fen and query?"

Hactar is a context engineering focused tool. A lot of your daily workflow with Hactar will consist of how manage context.

1. Add some files with /add

2. Remove files with /drop

3. Add docs with /docs-add

4. Add docs automatically with /docs-guess or by passing the flag --auto-docs

Hactar can use a combination of hard coded repo maps, RAG, and queries to an LLM to extract chunks of code. You can use this to query on the codebase

1. Use /find-code <query> to find code using plain language

2. Use /find-code <symbol> to find code using a matching symbol

Example:

/find-code Give me all the code that handles authentication

You can work with Hactar in a pair programming manner by enabling automatic linting, testing, and type checking. When enabled, Hactar runs these checks after applying code changes and attempts to fix any issues it finds.

1. Enable features with flags (--auto-lint, --auto-test, --auto-typecheck, or --auto-all), slash commands (/auto-lint, etc.), or your .hactar.toml file.

2. Write code by typing instructions.

3. Hactar will make changes and then automatically run the configured checks. If a check fails, Hactar will attempt to fix the code and re-run the check, up to the configured retry limit.

Hactar can also automate other parts of your workflow.

Hactar has tight integration a content repositry, this gives it the unique capability to be able to write documentation for you. It is not like the documentation generated by other agents. Hactar doc generation uses RAG so that the docs it generates are up to date and have less hallucinations.

1. Open hactar with hactar

2. Generate docs with /docs-gen <instructions>

3. Generate developer guide with /guides-gen

4. Update developer guide with /guides-update

Hactar is really good at looking up relevant documentation.

1. Open hactar with hactar

2. Use /docs-find <query> to lookup documentation

1. Open Hactar hactar

2. Create a new branch git checkout -b feature-awesome-cats

3. Give your hactar your instructions to hactar for a new

4. Use /plan to write a plan for implementing the feature

5. Use /agent-run to have Hactar implement the plan itself

1. Use /add to add images to context and /drop to drop iamges

2. Ask Hactar to analyze the image

   • What does this iamge show?

3. Use images for context

   • Fix the errors in screenshot

Hactar can be launched in multiple instances, but these can trip over each other if you aren't careful. You can prevent them from tripping over each other by using git worktrees.

# Create a new worktree with a new branchgit worktree add ../project-feature-a -b feature-a# Or create a worktree with an existing branchgit worktree add ../project-bugfix bugfix-123

# Navigate to your worktreecd ../project-feature-a# Run hactarhactar

# List all worktreesgit worktree list# Remove a worktreegit worktree remove ../project-feature-a

Hactar has tight integration with shells

• Hactar will automatically suggest commands with --auto-suggest-cmds enabled.

• You can shell commands with /sh and generate on by passing a query /sh run tests, /sh! <query> can be used to automatically accept and run the resulting command.

• You can run commands in a shell pipeline with hactar sh <query> and hactar sh! <query>

• Set AGENT_SAFE_ENV to true and enable --auto-cmds to let Hactar go wild

  • Warning: This is highly dangerous to data and should only be done in a VM. Don't let your LLM delete your data please!

Hactar can be used in scripts with hactar sh! <query>. It will return a shell command or output that can be chained. For example:

cat cats.txt | hactar sh! "return the cats as json" | jq

Often you will need to keep re-using documentaiton and references. Hactar includes features that help automate this cycle by parsing your doc in the background.

hactar/docs-gen <some extra instructions>

/add .hactar.guide.org

Hactar is developed in Common LISP so that it is maximally hackable and extensible. CL can be a barrier for many but my hope is that in the LLM era it is less one and the benefits outweight the cons.

The benefits are that Hactar is completely customizable. You could potentially build anything ontop of it.

A simple extension to hactar can be done by adding lisp to ~/.config/hactar/user.lisp. Let's add a new function to hactar and a command to print it:

(defun hello-world ()  (hactar:output (format nil "Hello World ~A" name)))(hactar:define-command hello (args)                "Print hello message to a user."                (let ((name (format nil "~{~A~^ ~}")))                  (hello-world name)))

Here we use the macro define-command to add a command to hactar. This will expose the hello-world function as slash command /hello.

To write rules use the defrule macro:

(defrule :prefer-custom-hooks "Prefer custom hooks over libraries where possible." :triggers '(:stack (:react)))

Hactar is pretty good at extending itself. You can give rule generation a try with the /gen-rule command. Hactar will attempt to write a rule for based on your instructions. Then it will add it to your user.lisp file. Please read any rules it generates first and don't blindly accept them.

A plugin in Hactar is just a lisp file. Instead of auto loading things we let you manually determine what plugins you want. You can load a plugin just like you would load a lisp file:

(load "plugin.lisp")

Hactar uses what is called an analyzer to process your code and determine things like stack, dependencies, lint things etc. Analyzers combine a hook, (or triggers), with a function. You can write them with defanalyzer. Here is an example of an analyzer that watches for AI comments and then adds those files to the context:

(defun is-ai-comment-event? (pathname event-type)  "Checks if a file event is relevant for the AI comment analyzer.   Specifically, if the file was added/changed and contains 'AI!' on a line."  (when (and (member event-type '(:file-added :file-changed))             (probe-file pathname))    (let ((content (read-file-content pathname)))      (when content        (search "AI!" content)))))(defanalyzer auto-add-ai-comment-file ((*file-event-hook* #'is-ai-comment-event?)) t (pathname event-type)  "Detects 'AI!' comments in files and automatically adds the file to the context."  (declare (ignore event-type))  (debug-log "Auto-add-ai-comment-file: Detected 'AI!' in" pathname)  (add-file-to-context pathname))

Agents in Hactar are standalone programs that perform autonomous tasks by wrapping Hactar as a library. Unlike the interactive REPL, an agent runs a loop to achieve a specific goal, continuing until a condition is met or it receives a signal to stop (like SIGINT). An agent is simply a Lisp file, making it easy to create and modify.

You can create a new agent using a starter kit with the create.agent subcommand.

To define an agent, you use the defagent macro. This macro sets up the main entry point and loop for your agent.

(defagent my-research-agent (query)  "An agent that researches a topic and writes a summary."  (:init (setup-research-environment))  (:run (perform-research-step query))  (:stop-condition (research-complete-p))  (:cleanup (cleanup-research-files)))

Agents can also be controlled via an HTTP/JSON-RPC API, allowing for more complex integrations.

Processors in Hactar handle processing the output from the LLMs.

You write one by using the def-processor macro. You will get the history of the current conversation and the current response will be last on the list.

Here is an example of a processor that handles searc/replace blocks:

(def-processor search-replace-processor (history)               "Parses and applies SEARCH/REPLACE blocks from the last assistant message."               (when history                 (let ((last-message (car (last history))))                   (when (string= (cdr (assoc :role last-message)) "assistant")                     (let* ((content (cdr (assoc :content last-message)))                            (blocks (parse-search-replace-blocks content)))                       (when blocks                         (format t "~&Applying ~A SEARCH/REPLACE block(s)...~%" (length blocks))                         (apply-search-replace-blocks blocks)                         (format t "~&Finished applying blocks.~%")))))))

To add a command to Hactar use define-command:

(defun hello-world ()  (hactar:output (format nil "Hello World ~A" name)))(hactar:define-command hello (args)                "Print hello message to a user."                (let ((name (format nil "~{~A~^ ~}")))                  (hello-world name)))

Hactar uses hooks as the pub/sub method. You can define your own hooks like this:

(nhooks:define-hook-type process-history (function (list) t)                         "Hook run after an LLM response is processed, allowing modification or action based on history. Handler takes the full chat history.")(defvar *process-history-hook* (make-instance 'hook-process-history))

Then use them like this:

(nhooks:add-hook *process-history-hook*                      (make-instance 'nhooks:handler                                     :fn #',name                                     :name ',name))#+end_src*** Writing Dot Commands:PROPERTIES::ID:       c2730ac9-7c9f-461d-a780-463f9195732f:CUSTOM_ID: writing-dot-commands.c1a407fd-bc97-4091-88d1-f5dec1db4048:END:Dot commands are a special command that only acts on the LLM text. You can think of them like a virtual file system. Any commands you add will be sent to the LLM as part of the prompt. The prompt will instruct it how that prompt should transform the text.An example is a simple ls command that asks an LLM to imagine the content of a file:#+begin_src lisp  (defdot ls (args)        "Usage: ls [path]  Lists directory contents. Acts like the OS 'ls' command.  When used on a file it should act like 'cat' command.  "        (let ((full-command (format nil "ls ~{~A~^ ~}" args)))          (get-llm-response full-command :dot-command-p t)          ))

Hactar is designed to let you quickly extend import sources. A similar development philosophy to devdocs, we want you to be able to import any of your common doc sources.

Hactar expects a import source to return three values:

• content

• title (defaults to the passed uri)

• metadata

Only the content is required and metadata will be generated by calling an LLM. Keep in mind though that the more you can hardcode the better for token usage and response times. It is silly to e.g pass the entire npm package.json to generate metadata for npm packages. You should return metadata whenever you can. Sources are flexible enough that if you hardcode everything it is possible to import docs without any LLM roundtrips.

The simplest source could be a file. We could define one like this:

(defsource file-source  :pattern "^file:(.+)$"  :params (filepath)  :priority 10  (lambda (filepath)    (let* ((path (uiop:native-namestring (merge-pathnames filepath *repo-root*))))      (if (probe-file path)          (values (uiop:read-file-string path)                  (file-namestring path))          (error "File not found: ~A" path)))))

Now you can use it like this:

./hactar import file:~/my-docs/react/myreactdocs.md

This isn't extremely useful. So let's take a look at how we might retrieve a web source:

(defsource http-source  :pattern "^https?://(.+)$"  :params (url-path)  :priority 5  (lambda (url-path)    (let* ((url (format nil "http~A://~A"                       (if (search "https" url-path) "s" "")                       url-path))           (content (fetch-url-content url)))      (if content          (values content (format nil "Web: ~A" url))          (error "Failed to fetch URL: ~A" url)))))

The macros you need to know about to write new import commands:

• defsource. You can use this to define a new import source

• defdocsource. Define API documentation sources for packages

A common scenario is giving agents API documentation that we know the source of markdown docs for a thing but the urls change slightly because of versions or domains etc. We can use the router and macro defdocsource to define lookup functions for specific documentation and their versions. Here is how we could define the path to a markdown doc for react versions greater than 19:

(defdocsource :name "react"        :version "19.^"        :platform "npm"        :uri "file:~/docs/react/MyReact19docs.md")

Hactar tries to make it dramatically easier to add things to context. The primary path to get most things for context is the web. Whether that is a search, browsing github etc. Eveyrtime you have to leave your dev tooling to do this is flow lost. We try to keep in Hactar and your IDE as much as possible. A way we do this is by building wrappers around common web sources so that they can be consumed by hactar as plaintext.

Engineering plaintext layers onto common web platforms is a whole niche of open source. And they are extremely useful but the barrier to using them is often pretty high. Sure you can consume your twitter as plaintext markdown, but good luck setting up all the infrastructure to do that in a couple hours much less five minutes. In hactar the goal is for everything web to be a command away. Want your raw LLM text for a blog post? Just one command. Want the markdown of the HN frontpage or a subreddit? One command for that which you cna pipe directly. Hactar brings the unix philosophy to the web. A herculean effort mostly impossible prior to LLM era.

To write new web commands you combine two tools the defwebcommand macro and the generic router tooling in Hactar. Turns out routing is useful for web requests too. (Rubyists know this)

Here is an example of an HN webcommand:

(defwebcommand hn  "Fetch news from news.ycombinator.com (Hacker News)."  (defwebroute hn-newest "Fetch newest posts from Hacker News"    ("newest" &rest args) (args)    :priority 10    (lambda () (get-hn-newest args)))  (defwebroute hn-top "Fetch top posts from Hacker News"    ("top" &rest args) (args)    :priority 10    (lambda () (get-hn-top args)))  (def-default-route ()    (lambda () (get-hn-front-page-md))))

Here is a list of some conventions I follow with Hactar code

• Follow The One True LISP Style Guide

• Subcommands should be prefixed with a dot e.g hactar pro.update

• Test extremely thoroughly (tests act as an LLM guardrail)

• Prefer hooks over extension

• Use macros instead of APIs

  • This is so we can swap out the underlying way things work. e.g if you always use the defanalyzer macro then the internal way analyzers work can change without requiring changes to the syntax. DSLs are the LISP way use them.

The release process is:

1. Tag the current state of main

2. push the tag

3. run make build

4. Use the outputted files and upload to releases

You can run the release script for this. By default it will be a dry run. Pass the --live-dangerously flag to actually make the release.

release --version 0.0.1 --description ./RELEASE_0_1.md