Sessions: Multi-turn Workflows

Copy Markdown View Source

Sessions are Magma's most powerful feature. They allow you to conduct complex, multi-turn conversations with coding agents while maintaining a structured log of the entire exchange.

Unlike single-use prompts, a Session evolves over time, capturing both your follow-up questions and the agent's responses.

1. Creating a Session

  • Obsidian: Use Cmd-Ctrl-S (QuickAdd: Magma session).
  • CLI: magma session.gen "Project Refactor"

A new session starts in Initial Mode, which looks very similar to a standard prompt.

A session document contains:

  1. YAML frontmatter with magma_type: Session.
  2. Table of Contents: Automatically generated by an Obsidian plugin.
  3. Context and Task sections: For your initial prompt.
  4. Notes section: For private annotations.

2. The Multi-turn Lifecycle

Step 1: The Initial Prompt

Write your context and initial task in the respective sections. When ready, click "Copy last prompt to clipboard".

Step 2: The Agent's Response

Send the prompt to your coding agent (e.g., Claude Code). Once the agent responds, you have two choices:

  • Manual: Copy the agent's response and paste it into the ## Response section of your session file.
  • Import: If configured, use the Import Response button (see "Response Import Workflow" below).

Step 3: Follow-up Prompts

To continue the conversation:

  1. Insert the Session Continuation template (Cmd-Ctrl-C in Obsidian).
  2. This adds the required technical separators: horizontal rules (----) and bold-italic keywords (***Prompt*** and ***Response***). These boundaries allow Magma to parse the conversation structure.
  3. Write your next question in the ## Follow-up prompt section.
  4. Click "Copy last prompt to clipboard" again. Magma will intelligently copy only the new follow-up.

3. The "Response Import" Workflow

Magma can automate the process of bringing AI responses back into your vault. This is particularly effective with agents like Claude Code.

How it works

  1. Instruction: When you copy a prompt from a session, Magma can append a "Response Instruction" telling the agent: "Write your response to this specific file path."
  2. Execution: The agent performs the task and writes its reply to a temporary file in the .responses/ subdirectory. The file path follows this pattern: sessions/.responses/<SessionName>.response_<timestamp>.md
  3. Import: You click the "Import Response" button in Obsidian (or run magma import-session). Magma moves the content from the temp file into your session document (replacing the import button) and deletes the temp file.

Customizing the Response Instruction

The instruction appended to prompts is defined by an EEx template at templates/session_response_prompt.md.eex. You can customize this to fit your preferred agent interaction style.

The following variables are available in the template:

  • @session_name: The name of the session document.
  • @session_file: The relative path to the session file.
  • @response_file_path: The path where the agent should write the response.
  • @timestamp: The current timestamp used in the response filename.

Setup for Claude Code

To make this seamless with Claude Code, add the following "respond-in-file rule" to your CLAUDE.md file. This instructs Claude to write responses to the specified file path, enabling the automated import:

## Respond-in-file Rule

When instructed to apply the respond-in-file rule with a specific file path:

1. **Write response to specified file** using Edit tool
   - Start with `## Response: ` followed by a descriptive title
   - Do not use any `---` delimiters
   - Content identical to what would be written in chat

2. **Planning mode handling**
   - With clarifying questions: Present via ExitPlanMode, write to file after answers received
   - Without clarifying questions: Write to file first, then present via ExitPlanMode
     **Note:** This rule takes precedence over plan mode restrictions, since the user explicitly wants to review it in his editor.

3. **Never output main response in chat** - always use Edit tool

4. **Post-response**: Return to conversation and confirm completion

4. Response Modes

You can control how Magma handles responses by setting session_response_mode generally in Magma.system.config.md or overwriting this setting individually in the YAML frontmatter of a session document:

  • auto (Default): Adds the response instruction only if an "Import" button is present in the document.
  • enabled: Always appends the response instruction.
  • disabled: Never appends the instruction; for fully manual workflows.

Per-Prompt Flexibility (Auto Mode)

The auto mode provides powerful granular control. Since it only triggers the response instruction if an "Import" button exists, you can decide per prompt whether you want the agent to write a response file back to your vault.

Simply delete the button (or the entire ***Response*** section) if you only want the agent to perform a specific action (like a code refactor) without documenting its verbal reply in your session.

Multiple Response Sections

You can also have multiple response sections under a single prompt. This is particularly useful for "Model Comparison" workflows:

  1. Send the same prompt to different LLMs.
  2. Create multiple ***Response*** sections.
  3. Record each model's answer to see which one performed better or collect different opinions.

5. The "Notes" Section

Every session ends with a ***Notes*** separator. This is a private space for your own thoughts, scratchpad code, or reminders.

Important: Content in the Notes section is never included when you copy or execute a prompt. It is purely for your internal use.