The Act

What is an Act?

An Act is a saved, reusable AI task. Instead of writing a long prompt every time you want Ghostwriter to do something, you pick an Act — like task, code-doc, unit-tests, or sonar-fix — add a short request if you want, and Ghostwriter runs the workflow for you.

Think of it like a saved recipe. Someone has already written down the ingredients (what files to look at), the instructions (what the AI should do), and the steps (how the work should proceed). You just choose the recipe and, optionally, tell it what you specifically want.

Without an Act, you might have to type something like:

"Please look through this project's source code, find all the public classes and methods that are missing documentation, and add clear comments explaining what they do, without changing any logic."

With an Act, you just type:

--act code-doc

Same result, far less typing — and it works the same way every time, for you or anyone else on your team.

What can an Act do?

Provide ready-made instructions for common tasks (documenting code, writing tests, fixing issues, preparing commits, and more).
Work on a whole project, a single folder, a single file, or a specific set of files.
Run once and give you an answer, or keep the conversation going so you can ask follow-up questions.
Reuse and build on another Act, so you don't have to start from scratch.
Come with sensible default settings, so it still works even if you don't specify everything yourself.

How to run an Act

The basic command looks like this:

--act <act-name> [optional request text]

A few examples:

--act help
--act task Explain this project structure
--act code-doc Add missing documentation comments
--act unit-tests Improve tests for parser classes

If you add text after the Act name, Ghostwriter treats it as your specific request and sends it to the AI along with the Act's built-in instructions.

If you leave the text out, Ghostwriter falls back to whatever default request the Act already has configured — or waits for the AI to prompt you first.

The quick shortcut: `>`

If you just want to describe a task without picking a specific Act, start your message with >. This is shorthand for the general-purpose task Act:

--act > summarize the project

One-time answers vs. ongoing conversations

Acts can behave in two different ways:

Non-interactive — the Act runs once. Ghostwriter sends your request, gets the AI's response, and finishes. This is best when your request is already clear and complete.

text --act code-doc Add Javadoc to this package

Interactive — the Act works like a chat. After the AI responds, you can ask for changes, add missing details, or keep going. This is useful when you're not sure exactly what you need yet.

text --act help

While in an interactive Act, you can use two special commands:

Command	What it does
`.`	Ends the conversation and finishes the Act.
`>`	Accepts the AI's last response and continues without adding a new message.

Running just part of a multi-step Act

Some Acts are made up of several steps, run one after another — for example, first analyzing a project, then making changes, then checking the results. These steps are called episodes.

By default, all steps run in order. But you can choose to run only specific ones by adding # after the Act name:

--act review#1,2 Check error handling

Add ! if you want Ghostwriter to stop after those steps instead of continuing with the rest:

--act review#1,2!

Symbol	Meaning
`#`	Separates the Act name from the list of steps to run.
`,`	Separates multiple step numbers.
`!`	Stops after the selected steps instead of continuing normally.

Anatomy of an Act file

Every Act is defined in a simple text file using a format called TOML — a plain, readable way to store settings, similar to a configuration file. You don't need to be a programmer to read or edit one.

Where Act files live

Ghostwriter can load Acts from a few places:

Built into Ghostwriter itself (ready to use out of the box).
A folder you configure for your own custom Acts.
A web address (http:// or https://).
A direct path to a specific .toml file.

If you create a custom Act with the same name as a built-in one, your version can override or extend the built-in behavior.

The main building blocks

Here are the pieces you'll see in most Act files:

description — A short, human-readable explanation of what the Act does.

description = '''
Explains what this Act does.
'''

instructions — The behind-the-scenes guidance given to the AI about how it should behave.

instructions = '''
You are a helpful assistant working inside this project.
'''

inputs — The actual prompt sent to the AI. This is where your request usually gets inserted.

inputs = '''
# Task

${public.prompt}
'''

An Act can also have several prompts instead of one — see Multi-step Acts (episodes) below.

basedOn — Lets one Act reuse and build on another, instead of repeating everything from scratch.

basedOn = "task"

[default] — A section of fallback values, used only if nothing else already provided them.

[default]
gw.path = "glob:."
public.prompt = "Summarize the current project."

[gw] — A section of technical settings that control how the Act runs:

Setting	What it controls
`gw.model`	Which AI provider/model to use.
`gw.path`	Which files or folders to look at (e.g., `glob:.`).
`gw.threads`	How many files to process at the same time.
`gw.excludes`	Files or folders to skip.
`gw.nonRecursive`	Whether to skip looking inside subfolders.
`gw.interactive`	Whether the Act should behave like a chat.

A minimal complete Act file looks like this:

description = '''
Explains what this Act does.
'''

instructions = '''
You are a helpful assistant working inside this project.
'''

inputs = '''
# Task

${public.prompt}
'''

[gw]
interactive = true
path = "glob:."

Reading it line by line: the description tells a human what it's for, the instructions tell the AI how to behave, the inputs line inserts your actual request, and the [gw] section says "run as a chat" and "look at everything in this project."

Placeholders — `${...}`

Act files can include placeholders like ${public.prompt} or ${public.projectName}. Ghostwriter automatically fills these in at run time with the right value — your request, the project name, a configuration setting, and so on.

A few examples you might see:

${public.prompt}
${public.projectName}
${sonar.host}

One important rule (mainly for AI assistants editing Act files): when an AI is asked to create or modify an Act file, it must leave placeholders exactly as ${...} and never rewrite, guess, or "fill in" a value on its behalf. Ghostwriter resolves the actual value automatically when the Act runs — substituting it ahead of time would break that mechanism.

Including outside content

You can pull in text from another file or a web page using >>>:

>>> file://docs/shared-instructions.md

This is handy for sharing common instructions across several Acts without copy-pasting them everywhere.

Customizing a single step

If an Act has multiple steps, each step can have its own small settings block at the top, marked with ---. This lets you, for example, use a different AI model for just one step:

---
gw.model: ${public.ai.model}
enabledTools:
  - get_bindex
  - pick_libraries
---
Analyze the library choices for this project.

Reusing another Act (`basedOn`)

Rather than writing a new Act from nothing, you can base it on an existing one and just add or change what's different:

basedOn = "task"

instructions = '''
$$super.value$$

Also follow this extra project rule.
'''

Here, $$super.value$$ means "keep whatever the parent Act already said here" — so this child Act keeps all of task's original instructions and simply adds one more rule at the end.

Multi-step Acts (episodes)

Instead of a single prompt, inputs can be a list of prompts — one per step:

inputs = [
  '''
  # Analyze
  Review the project and identify risky files.
  ''',
  '''
  # Update
  Update the selected files and validate the changes.
  '''
]

Ghostwriter runs each step in order, one after another, unless you choose specific steps using the # syntax described earlier.

Step-by-step: create and run your own Act

Let's build a simple custom Act that reviews project documentation.

1. Create a new file in your custom Acts folder, named review-docs.toml.

2. Add the content:

description = '''
Reviews project documentation and suggests improvements.
'''

instructions = '''
You are a helpful technical writer. Review documentation for clarity, accuracy, and completeness.
'''

inputs = '''
# Task

Review the documentation in this project and suggest improvements.

${public.prompt}
'''

[default]
gw.path = "glob:src/site/**"
public.prompt = "Focus on pages that are unclear for new users."

3. Run it with no extra request — it will use the default focus defined above:

--act review-docs

4. Or run it with your own specific request:

--act review-docs Check whether the Act documentation explains episodes clearly

5. If interactive mode is turned on, you can keep the conversation going after the first response — just type . when you're done, or > to continue without adding anything new.

That's it — you've created a reusable, shareable AI workflow.

Quick reference

Running an Act

--act <act-name> [request text]
--act > <quick task request>

Selecting steps in a multi-step Act

--act <act-name>#1,2      run only steps 1 and 2
--act <act-name>#1,2!     run steps 1 and 2, then stop

During an interactive (chat) Act

Type	Effect
`.`	Finish the Act.
`>`	Continue without a new message.

Common [gw] settings in an Act file

Setting	Meaning
`gw.model`	Which AI model to use.
`gw.path`	Which files/folders to process.
`gw.threads`	How many files to process at once.
`gw.excludes`	What to skip.
`gw.nonRecursive`	Whether to skip subfolders.
`gw.interactive`	Whether to run as a chat.

Where to go next

This page covers everything you need to use and create Acts day-to-day. If you're a developer interested in how Acts are implemented internally (the classes and code that power this feature), that's covered in the separate developer-facing documentation.

https://www.free-Counters.org