StudyLoopGitHub

Keep your study notes in Obsidian or xTiles.

Publish a view of Today and your plans where you already keep your notes. The original StudyLoop plan stays authoritative; changes to a published copy do not update it.

Two kinds of Obsidian export

Available in 0.1.0

Session-memory export

Export AI coding-session summaries into AgentMemory/. This is the existing, opt-in session-export --obsidian workflow.

Read the session-export guide
In the v0.2.0 tag

Plan and Today projections

Publish a glanceable Today note, active plans, and learning records into Study/. StudyLoop replaces only files carrying its own marker, so it refuses to overwrite a note you wrote by hand — it will tell you and stop rather than take a guess.

One source, useful views, explicit notes back

This is deliberately not two-way sync. A projection can always be rebuilt from the StudyLoop plan, so an Obsidian edit cannot silently change what your next study session follows.

StudyLoop plan Markdown is the source of truth. Publishing creates StudyLoop-owned Today, plan, and learning record notes in Obsidian. A separate learner-owned notes file can be read back only with an explicit pull command.
Source of truthStudyLoop plan MarkdownEdited through StudyLoop
Obsidian projectionsToday · Plans · Learning recordsRegenerated by StudyLoop
Your spaceplan-id.notes.mdRead only after an explicit brain pull

Six steps, all of them on your own disk

The diagram above is the data model: one source, views of it, one explicit way back. This is what you actually do.

Publishing a StudyLoop plan into an Obsidian vault, in six stepsSix steps in one straight line, all of them on your own machine. Point StudyLoop at a vault, preview with a dry run, publish, read the notes in Obsidian, write your own thoughts in a separate notes file StudyLoop never touches, and pull those notes back to yourself. Nothing on this diagram sends anything over a network.1Point StudyLoop at a vaultA missing folder is refused unless you add --create.studyloop brain enable obsidian --vault ~/MyVault2See what it would writeLists every file, writes nothing.studyloop brain publish --dry-run3Notes appear in your vaultToday's note plus every active plan.studyloop brain publish4Read it in ObsidianStudy/Today.md and Study/Plans/<plan-id>.md5Write in your own fileStudy/Plans/<plan-id>.notes.md is yours. StudyLoop never writes it.6Your notes come back to youNot to the plan. You decide what belongs in it.studyloop brain pull <plan-id>
StudyLoop sends nothing anywhere in these six steps: every one is a file on your own disk. Your vault’s own arrangements are a separate matter — Obsidian Sync or a plugin can still move those files. Steps 4 and 5 are the two only you can do — and step 5 is the one file in the vault StudyLoop will never write.
  1. Point StudyLoop at a vault studyloop brain enable obsidian --vault ~/MyVaultA missing folder is refused unless you add --create.
  2. See what it would write studyloop brain publish --dry-runLists every file, writes nothing.
  3. Notes appear in your vault studyloop brain publishToday's note plus every active plan.
  4. Read it in ObsidianStudy/Today.md and Study/Plans/<plan-id>.md
  5. Write in your own fileStudy/Plans/<plan-id>.notes.md is yours. StudyLoop never writes it.
  6. Your notes come back to you studyloop brain pull <plan-id>Not to the plan. You decide what belongs in it.

What StudyLoop refuses to do

Publishing is designed to be safe to run repeatedly and safe to run into a vault you already use. Four refusals, all of them checked in code rather than promised in prose:

  • A note you wrote by hand at a path StudyLoop wants is refused by name, and nothing is written. StudyLoop replaces only files carrying its own studyloop: frontmatter marker.
  • A projection belonging to a different plan is refused too, so renaming a plan cannot silently consume the old plan’s note.
  • A symbolic link at the target is refused. Replacing it would destroy something you created and StudyLoop cannot rebuild.
  • Anything outside the folder you named is refused before a byte is written, including paths that try to climb out with .. and folders that are symlinks pointing elsewhere.

Republishing a plan that has not changed writes nothing at all and leaves the file’s timestamp alone, so a synced vault sees no churn. Publishing also never deletes: if you remove a plan, its projection stays until you remove it too.

Four keys, and it is off until you set one

With no second_brain section StudyLoop imports no provider code, writes nothing, and offers nothing.

~/.config/studyloop/config.yaml
second_brain:
  provider: obsidian          # none (default) | obsidian | xtiles
  vault_path: ~/Documents/MyVault
  folder: Study               # the folder inside the vault StudyLoop owns
  backlinks: true             # [[wikilinks]] to your own notes, when available

Earlier development builds had four more keys — use_cli, vault_name, template and daily_note — for an Obsidian command-line adapter that was withdrawn before release. If any of them is still in your config, StudyLoop now says so and stops rather than ignoring it.

Preview first, then publish

These commands are not in StudyLoop 0.1.0

Use a checkout containing the v0.2.0 changes. Run studyloop brain --help to check that your installation has these commands before changing configuration.

  1. 1

    Check what is configured

    Status is read-only. It reports the provider, destination, and whether publishing is available.

  2. 2

    Preview before writing

    Use a dry run to see the exact vault-relative files StudyLoop would create.

  3. 3

    Publish the useful subset

    The default is Today plus active plans. Draft and finished plans stay out unless you explicitly include them.

  4. 4

    Keep your own notes separate

    Write beside a plan in its .notes.md file, then pull those notes only when you want to fold them back into the source plan.

Second-brain commands
studyloop brain status
studyloop brain enable obsidian --vault ~/Documents/MyVault
studyloop brain publish --today --dry-run
studyloop brain publish
studyloop brain template --install

brain enable preserves the rest of your StudyLoop configuration. A missing vault is refused unless you deliberately add --create.

A small, predictable folder

The default destination is Study/ inside the chosen vault. Today stays short: one next action, a few alternatives, due reviews, and active topics.

Vault layout
MyVault/
└── Study/
    ├── Today.md
    ├── Plans/
    │   ├── python-decorators.md
    │   └── python-decorators.notes.md
    └── Learning Records/
        └── python-decorators/
            └── LR-0001.md

Generated files identify themselves

StudyLoop only replaces a file carrying its matching studyloop: ownership marker. If a target is unmarked or belongs to another plan, publishing stops rather than overwriting it.

Template-created notes have no ownership marker and remain yours.

Pull notes; do not synchronise them silently

Put personal observations beside the generated plan using the same plan ID and a .notes.md suffix. The pull command prints that file without changing either it or the source plan.

Terminal
studyloop brain pull python-decorators

# Then decide what, if anything, belongs in the real plan.
studyloop plan show python-decorators --markdown

Served by your assistant, not by StudyLoop

xTiles is a visual planner many people already live in. StudyLoop does not talk to it, and that is the design rather than a gap: you connect both StudyLoop’s MCP server and xTiles’ hosted connector to your assistant, then ask the assistant to move today’s study into your planner. No xTiles credential ever enters StudyLoop, so there is none for it to lose.

The source documentation includes planner, project, and wind-down prompts. A recorded Kiro run validated planner and wind-down writes; it did not validate a complete project board. The connector cannot create a board view, and created pages may not be visible from the project home. Start with one planner tile and check it in xTiles.

What leaves your machine

Your assistant sends the content

Running one of the prompts — or the opt-in wind-down skill, once you enable it — sends the plan text, today’s next action and the session’s learning record to your assistant’s model service and on to xTiles’ cloud. StudyLoop itself never opens a network connection, but note that your study material also reaches your assistant’s model service during ordinary assistant use. Obsidian remains the free, entirely local alternative.

Where the boundary is, and when your study text crosses it

This is the diagram worth reading closely, because it answers the question the prose can only assert: StudyLoop is not on the arrow that leaves your machine.

Moving StudyLoop study into xTiles through your own assistant, in six stepsSix steps. The first two are local configuration: record xTiles as your provider and install the wind-down skill. The third attaches the hosted xTiles connector and authorises it in a browser, which is already traffic to xTiles — setup, not study content. StudyLoop never talks to xTiles itself. The fourth step is you running a prompt; only then does study content leave the machine, going to your assistant’s model service and through the connector to xTiles’ cloud, and which content depends on the prompt. In the sixth step you open xTiles and see the result, which StudyLoop can neither see nor verify.YOUR MACHINE — CONFIGURATION ONLY1Record the choiceNo vault, no path, no credential. Stays on your machine.studyloop brain enable xtiles2Install the wind-down skillSilent unless the provider is xtiles and an xtiles server is connected.studyloop install agents3Attach the connector, and authorise itSetup traffic: this reaches xTiles to sign in. No study content yet.claude mcp add --transport http xtiles …4You run one of the three promptsNo study content has left your machine until this moment.leaves your machine5Your study content crossesWhatever that prompt includes or fetches — to the model service, then xTiles.6You open xTiles and see itStudyLoop cannot see what was sent, and cannot verify what arrived.
The dashed box is local configuration, not a promise that the network is untouched — step 3 signs in to xTiles. The thick arrow is the one carrying your study content, and StudyLoop is not on it: your assistant is the only thing holding both connections, which is also why you end this by removing the xtiles server from your assistant’s own MCP settings rather than with a StudyLoop command.
  1. Record the choice studyloop brain enable xtilesNo vault, no path, no credential. Stays on your machine.
  2. Install the wind-down skill studyloop install agentsSilent unless the provider is xtiles and an xtiles server is connected.
  3. Attach the connector, and authorise it claude mcp add --transport http xtiles …Setup traffic: this reaches xTiles to sign in. No study content yet.
  4. You run one of the three promptsNo study content has left your machine until this moment.
  5. Your study content crossesWhatever that prompt includes or fetches — to the model service, then xTiles.
  6. You open xTiles and see itStudyLoop cannot see what was sent, and cannot verify what arrived.