MelozWrite

How it works

How you and your agent work on one document

A MelozWrite project is a document you keep coming back to: a spec, a plan, a memo, a weekly status update. Your AI agent can read it and suggest changes. You can edit it any time. Nothing your agent suggests goes in until you approve it. Here's how that works, step by step.

1. What's in a project

A project is a short overview file plus one markdown file per section. Every kind of project uses the same layout:

My Plan/
  SPEC.md
  sections/
    goal.md
    timeline.md
    risks.md

SPEC.md holds the overview. Each section gets its own file in sections/, so you and your agent can work on one part without touching the rest. When you sign in, you get a sample project to try.

2. Connecting your agent

Your agent connects through MCP (Model Context Protocol), an open standard that lets AI assistants use tools in other apps. MelozWrite gives your agent a small set of tools for reading and editing projects. Each connection belongs to one account, so your agent only ever sees your workspace.

  • You sign in once, and the editor uses that session for everything you do.
  • Your agent uses an API key from the Connect page. A key works for one workspace and can't be moved to another.
  • Anyone can see the list of tools below. None of them run until you're signed in or your agent uses its key.
  • project_list
  • project_create
  • project_open
  • structure_get
  • section_read
  • section_write
  • suggest
  • await_hitl
  • credits_summary

3. Your agent suggests, you decide

Your agent reads first, then suggests. A suggestion sits in Approvals until you approve or reject it. A change can also land through a direct save: the Save button in the editor, or section_write with apply: true.

  1. 1 · project_create / project_list

    Start or find a project

    Start a new spec, plan, article, memo, review, or status update, or list the projects in your workspace.

  2. 2 · project_open

    Open the project

    Open a project by its ID or its owner/repo name. A missing project and someone else's project return the same "access denied" error, so an agent can't fish for other people's work.

  3. 3 · structure_get

    See the outline

    List the overview and every section. Each title comes from the section's first heading, or its file name if there isn't one.

  4. 4 · section_read

    Read a section

    Load one section. The agent only sees paths inside the project, and any path that tries to step outside is refused.

  5. 5 · suggest

    Suggest a change

    Draft new markdown for a section and send it to Approvals. The project doesn't change yet. Each AI draft costs one credit.

  6. 6 · HITL approve

    You decide

    Open Approvals. Approve writes the section. Reject leaves it as it was. Your agent can't approve its own suggestions.

  7. 7 · section_write / credits_summary

    Save and check credits

    Approving saves the change for you. To save without a review, call `section_write` with `apply: true`. `credits_summary` shows your credit balance and history.

Loop
flowchart TD
  A[Agent or human] --> L[project_list / project_create]
  L --> B[project_open]
  B --> C[structure_get]
  C --> D[section_read]
  D --> E[suggest]
  E --> F[Pending proposal JSON]
  F --> G{Human in /app/hitl}
  G -->|Approve| H[Kit markdown written]
  G -->|Reject| I[Kit unchanged]
  D --> J[Portal editor]
  J -->|Save apply:true| H
  J -->|Propose apply:false| F
  E -.->|live model: 1 credit| K[credits_summary]
  A --> K

The same loop as a flowchart.

After suggest, the agent checks await_hitl with the proposalId. Each check answers right away. If the suggestion is still pending, the agent waits and checks again.

4. What you get

  • One outline for both of you. You and your agent see the same list of sections, and each new section is a plain markdown file.
  • Work one section at a time. Keep requirements, risks, and notes in their own sections. You save edits in the editor, and your agent suggests changes to the same sections.
  • You see every suggestion first. Your agent's suggestions wait in Approvals until you approve them.
  • You only pay for AI drafts. Writing, saving, and approving are free. Each AI draft from Suggest costs one credit.

5. Try it

  1. Sign in.
  2. Open your projects and pick the sample project.
  3. Change a section and press Save. Or type a prompt and press Suggest.
  4. Open Approvals and approve or reject the suggestion.
Sign inOpen MelozWriteRead the guide