asistan

local-first project memory for ai coding tools

works with cursor · github copilot · claude code · any ai tool that reads files

---

asistan bootstraps a portable .assistant/ workspace inside any project so your ai coding tools always have the right rules, memory, workflows, and prompts at hand.

what is asistan

asistan is a small cli that writes a structured set of markdown files into your project. those files become the persistent context every ai session reads before touching your code. no cloud sync, no vendor lock-in, no daemon — just files you own.

why it exists

ai tools are powerful but stateless. every new chat forgets your architecture, your naming conventions, your constraints. asistan gives each project a memory it carries with it, kept with your workspace and optionally versioned with your repository when you want shared team context.

features

• asistan init — writes .assistant/ files and cursor rules from embedded templates
• asistan doctor — validates that all declared files are present and readable
• asistan version — prints build info
• yaml-driven config — override the default layout or add your own templates
• cursor integration — generates .cursor/rules/asistan.mdc with alwaysApply: true
• --force flag — safe re-init without deleting unknown files
• zero runtime dependencies — single static binary

---

installation

requires go 1.22+.

git clone https://github.com/okanck/asistan
cd asistan/cli
go build -o bin/asistan ./cmd/asistan
cp bin/asistan ~/.local/bin/asistan   # or /usr/local/bin/asistan

asistan version

---

quick start

cd my-project
asistan init --path .
asistan doctor --path .

open .assistant/project-context.md and fill in the blanks.

---

generated structure

my-project/
  .assistant/
    global-rules.md        # ai behaviour rules
    project-context.md     # project memory scaffold
    repo-map.md            # folder/purpose table
    workflows.md           # bootstrap, triage, implementation, review, release
    prompts/
      triage.md            # classify input: critical-now / this-week / ignore
      implementation.md    # plan → approve → implement → verify
      review.md            # [blocking] / [suggestion] / [ok] format
  .cursor/
    rules/
      asistan.mdc          # cursor rule: always read .assistant/ files

---

commands

asistan init

flags:
  --path string     target project directory (default ".")
  --force           overwrite existing files
  --config string   path to user config yaml

skips existing files unless --force is set. re-running init is always safe.

asistan doctor

flags:
  --path string     target project directory (default ".")
  --config string   path to user config yaml

exit codes: 0 ok · 1 missing files · 2 config error

asistan version

prints version and commit hash.

---

cursor integration

asistan init writes .cursor/rules/asistan.mdc with alwaysApply: true. cursor loads it automatically for every conversation in the project.

the rule tells cursor to read your .assistant/ files before answering — so it knows your architecture, constraints, and workflows without you repeating them.

---

configuration

override the default layout by passing --config path/to/config.yaml:

assistantDir: .assistant

files:
  - path: global-rules.md
    template: global-rules.md
  - path: project-context.md
    template: project-context.md

workspaceFiles:
  - path: .cursor/rules/asistan.mdc
    template: cursor/asistan.mdc

variables:
  projectName: ""

user config is overlaid on top of the embedded default. top-level keys replace; slices replace (not append).

---

roadmap

see ROADMAP.md.

contributing

see CONTRIBUTING.md.

license

MIT

---

made with love for engineers who live inside too many repositories.