Make Most of Your Workspace with Alter.md

No jealousy, we also support Claude.md and Agents.md

AuthorAuthor

Samuel ROY & Olivier Legris
January 23, 2026

Hey everyone,

This week we're diving into one of Alter's most powerful (new) features: grounding files.

If you've ever wished you could tell Alter exactly how you work—once—and have it remember that forever, this is for you.

Alter now supports Alter.md, Agents.md, and Claude.md 

What Are Grounding Files?

Grounding files are markdown documents that live in your workspace and automatically load during every session done in a workspace.

They define:

  • Who you are - Your role, expertise, communication style

  • How you work - Your processes, preferences, workflows

  • What matters - Your priorities, constraints, best practices

Think of them as your personal AI operating manual.

Best Practices

  1. Keep it lean - Around 60 lines maximum

  2. Be specific - Vague instructions = vague results

  3. Use progressive declaration - Link to other .md files for detailed rules

  4. Stay organized - One file per concern (checklist.md, templates.md, etc.)

Real Example: Our Release Workflow

Here's how we use grounding files for Alter's weekly releases:

  • Who we are: Co-founders managing weekly releases

  • What we value: Efficiency, clear systems, direct communication

  • High-level workflow: Input → WIP → Final → Publish

Checklist.md (detailed)

  • Exact folder structure for each release

  • Day-by-day execution steps

  • Tool-specific workflows (Screen Studio → Auphonic → Beehiiv → Discord)

  • Checklists for each phase

How to Get Started

  1. Open any workspace in Alter

  2. Click "Alter.md" button (or create a new file)

  3. Write 50-60 lines describing:

    • Your role and expertise

    • How you prefer to work

    • Your communication style

    • Key workflows or processes

  4. Save it - It's now active for all future sessions

  5. Reference it - Link to other .md files for detailed rules

The Power of Progressive Declaration

Instead of one massive 500-line Alter.md, use this structure:

Alter.md (60 lines)
├── checklist.md (detailed steps)
├── templates.md (reusable formats)
├── tools.md (software & scripts)
└── best_practices.md (guidelines)

Your main Alter.md stays clean and readable. When AI needs details, it can look in the linked files. Best of both worlds.Full Changelog.

Grounding files are how you scale from "I have a system" to "My system scales itself."

See you next week.

Olivier & Samuel

Full Changelog

New Features & Enhancements

  • Workspace Instruction Files: Support for Alter.md, Claude.md, and AGENTS.md files to provide project context and instructions

  • Workspace Permissions: Added read, write, and execute permissions support for workspace operations

  • Workspace File System: New workspace_fs tool for complete file system operations without the need of bash

  • Hub Stop Button: Added stop button with improved stop streaming between tool calls

  • Copy Conversation ID: Add copy ID button in hub to use with Run Action tool

Bug Fixes & Stability

  • Hub Input: Fixed prefix search issues when search term starts with or is preceded by a space

  • Transcription: Optimized CPU resource usage

  • Model Override: Fixed last message model overriding global user model of choice

  • Custom Endpoints: Fixed conversation failure after tool call with empty arguments

  • Deleted Conversations: Fixed deleted conversations not being removed from sidebar

  • Workspace Performance: Faster glob matching on large folders

  • Model Synchronization: Fixed current model synchronization issues in hub

  • Workspace Context: Fixed fork reuse of workspace context and proper context removal

  • Notch Integration: Fixed workspace attachment as context in notch

Videos on Alter