A simple AI coding tool for human-guided, scaffold-first development.
ParrotCode is an AI coding environment for working with code editing through AI, with a focus on local AI models.
It lets you move through code changes in small, reviewable units while the user decides the goal, scope, mode, and permission level.
To make local AI easier to handle, ParrotCode provides Plan / Edit modes, level limits, Confirm / Full access, prompt structuring, prompt templates, path drag and drop, and command hooks.
After configuring the endpoint and model for the first time, you can select a project and start AI coding.
- Select a project
- Create a thread
- Choose the mode, level, and access setting
- Write or structure a prompt
- Review the AI investigation and edit results
Create threads for each project folder and save AI conversations, tool execution results, changed files, and hook results as a timeline.
Switch between Plan / Edit depending on the task.
Use Lv1 to Lv5 limits to set the maximum difficulty and change risk level you want to allow the AI to handle.
Switch between Confirm mode and Full access to decide whether AI operations require confirmation or can proceed directly.
Convert a rough request into a structured task prompt before running it, or skip structuring and run the prompt as-is.
Organize the goal, target, scope, requirements, constraints, and completion conditions into a prompt that is easier for AI to follow. You can also drag and drop project files or folders into the prompt fields to insert project-relative paths.
Run user-defined local commands before sending a prompt to AI or after receiving an AI response.
In ParrotCode Settings, you configure the AI endpoint used by ParrotCode.
The main settings are:
Base URL
Sets the AI API endpoint.
Model ID
Sets the model name to use.
API Key
Sets the API key if required.
The same configured model is used for normal AI execution and prompt-related helper features such as prompt structuring and hook summary placeholders.
ParrotCode lets you switch execution modes depending on the task.
| Mode | Description | Main use |
|---|---|---|
| Plan | Investigates and creates a plan without editing files | Checking change direction and impact scope |
| Edit | Investigates code, edits files, and reads back changed files | Normal code editing, file creation, and small fixes |
For lightweight changes or clearly targeted create/modify tasks, ParrotCode internally chooses a smaller task route and avoids unnecessarily long AI loops.
Before running a prompt, ParrotCode can help convert a rough request into a structured task prompt.
Before running a prompt, ParrotCode asks whether to structure the prompt first or run it as-is. Structure & Review uses the configured AI model to rewrite the current request into a structured Markdown task prompt and puts it back into the prompt field for review. If important information is missing or risky, the structured result may include short Prompt notes. Review those notes and adjust the prompt before running it. Run as is skips prompt structuring and runs the current prompt directly.
You can choose:
Structure & Review
Rewrites the request into a structured Markdown prompt and puts it back into the prompt field for review.
Run as is
Skips prompt structuring and runs the current prompt directly.
Prompt structuring uses the configured AI model. It does not require a separate prompt-assist model.
Lv1 to Lv5 limits let you set the maximum difficulty and change risk level you want to allow the AI to handle.
| Level | Main use | Examples |
|---|---|---|
| Lv1 | Definitions with almost no logic | DTOs, Options, Results, Enums, constants |
| Lv2 | Small logic without side effects | Validators, mappers, formatters, calculations, decisions |
| Lv3 | Limited processing with external I/O | Files, DB, HTTP, config loading, repositories, API clients |
| Lv4 | Coordination across multiple pieces | Services, policies, managers, coordinators, orchestrators |
| Lv5 | Large or sensitive changes | Permissions, safety controls, async processing, dangerous operations, build settings, large refactoring |
You can choose whether AI operations require confirmation.
| Access | Description |
|---|---|
| Confirm mode | Requires confirmation before file changes and similar operations |
| Full access | Reduces confirmations and lets the task proceed more directly |
If Mode decides “what to do,” Access decides “how much confirmation is required while doing it.”
ParrotCode includes a Prompt Form and Markdown template for organizing AI requests.
Content entered in the form can be converted into Markdown and appended to the prompt field with Apply to prompt.
You can drag and drop files or folders from the selected project into the main prompt field or prompt form fields. ParrotCode inserts project-relative paths. Paths outside the selected project are ignored, and up to 50 dropped paths are inserted at once.
## Operation
Write the type of operation.
Example: Auto / Create / Modify / Delete / Move / Rename / Plan
## Target
Write the file, folder, screen, class, or feature to create or modify.
Example: Create a new C# file: UserProfileValidator.cs
## Scope
Write the scope you want to allow the AI to handle.
Example: Only create the new validator file. Do not modify existing files.
## Purpose
Write why this change is needed.
Example: Create a small validator for basic user profile values.
## Context / Background
Write the current state, assumptions, related background, and notes.
Example: This is a small C# project. There is no existing validation class.
## Requirements
Write the requirements that must be satisfied.
Example:
- Create a public UserProfileValidator class.
- Create a UserProfileValidationResult class.
- Treat null profile as invalid.
- Treat empty Name as invalid.
- Treat Email without @ as invalid.
## Constraints
Write what must not be done, what must not be changed, or what APIs must not be used.
Example:
- Do not use external packages.
- Do not write to console.
- Do not read or write files.
- Do not modify unrelated files.
## Non-goals
Write what is not part of this task.
Example:
- Do not add database access.
- Do not add web API code.
- Do not create a validation framework.
## Completion conditions
Write the conditions for considering the task complete.
Example:
- The new file is created.
- The validator and result classes are implemented.
- The code is easy to review.
## Examples / Notes
Write additional notes, examples, expected output, or references.
Example: This is intended as a small Lv2-style task.Command Hooks let you run user-defined local commands before sending a prompt to AI or after receiving an AI response. These are not commands that the AI autonomously chooses and executes. They are external processes configured by the user in advance.
Warning
ParrotCode does not include built-in dedicated build verification, backup, undo, or rollback features. Prepare any verification or restore workflow yourself by using external tools such as Git, build commands, test commands, restic, or Kopia. Command Hooks allow you to run those commands before and after AI work.
Before send
Runs before sending the prompt to AI.
Examples: snapshot saving, work log creation, pre-checks
After response
Runs after the AI response.
Examples: post-change snapshot saving, log output, external tool integration
Each hook can have a name, command, enabled/disabled state, failure handling behavior, and timeline visibility setting.
Failure handling has three options:
Fail fast
Stops that hook phase immediately when the hook fails and marks the run as failed.
Fail later
Runs the remaining hooks first, then marks the run as failed at the end.
Warn
Continues the main run even if the hook fails, and treats the failure as a warning.
Hook commands can use the following placeholders.
When these placeholders are used, ParrotCode generates short summaries using the configured AI model. If summary generation is unavailable, ParrotCode falls back to a simple local summary.
{{prompt.summary}}
Replaced with a short summary of the user's request.
{{result.summary}}
Replaced with a short summary of the AI response and changes. This is mainly useful for After response hooks.
For example, you can run syntax checks, builds, snapshot saves, or pass work logs to external tools after the AI response.
Hook command examples:
Use the AI response summary as a Git commit message after the AI response:
git add .
git commit -m "{{result.summary}}"
Save the project state with restic:
restic backup .
Save the project state with Kopia:
kopia snapshot create .
ParrotCode's execution flow is designed not to let AI keep thinking freely, but to use local AI in units that are less likely to break down.
Local AI is useful, but compared with powerful cloud AI, it has limits in speed, reasoning stability, and consistency over long tasks. If you let it handle a wide range of changes for too long, it can drift away from the goal, touch unrelated files, or get stuck in long correction loops.
For that reason, ParrotCode does not simply hand a large task over to AI. Instead, the user first decides the goal, scope, mode, level, and access settings. The AI proposes investigation and edit actions within that frame, and ParrotCode checks whether each action may be executed.
In other words, ParrotCode is not a tool for maximizing AI autonomy. It is an AI coding environment for moving through AI-assisted code edits in small, reviewable, human-controlled steps.
flowchart TD
A[User prompt] --> B[Project / Thread]
B --> C[Mode / Level / Access]
C --> D[Route and level check]
D -->|Blocked| X[Stop and show reason]
D -->|Manual operation| Y[Manual handoff]
D -->|Allowed| E[Before send hooks]
E --> F[Build AI request]
F --> G[AI response]
G --> H[Parse action]
H --> I[Validate action]
I -->|Blocked| J[Show blocked result]
I -->|Allowed| K[Execute tool action]
K --> L[Show result in timeline]
L --> M[Update changed files / run state]
M --> N{Finished?}
N -->|No| F
N -->|Yes| O[After response hooks]
O --> P[Save history and metrics]
In ParrotCode, the user defines the task frame before running AI.
Prompt
What you want to do
Project
Which project folder is targeted
Mode
Whether to run in Plan or Edit
Level
How far Lv1 to Lv5 should be allowed
Access
Whether to use Confirm mode or Full access
This frame becomes the upper limit of what the AI is allowed to handle.
For example, Plan mode does not edit files. If Lv2 is selected and the task is judged to be Lv4 or Lv5, it is blocked before execution. In Confirm mode, file changes and similar operations can require user confirmation.
The run is based not on what the AI wants to do, but on what the user allowed.
When ParrotCode receives a prompt, it first classifies the task type and difficulty.
Route
What kind of task route this is
Level
How difficult or risky the change is
Targets
Whether the target files or target scope are clear
Constraints
What constraints must be followed
At this stage, tasks that exceed the selected level, tasks with overly vague targets, or tasks that look dangerous are blocked.
Operations such as file deletion, move, and rename are treated as manual operations when they should be judged directly by the user.
This check decides the range in which the task may be handled before asking the AI to proceed.
ParrotCode has two broad execution paths.
flowchart TD
A[Allowed task] --> B{Task route}
B -->|Bounded route| C[Deterministic bounded flow]
B -->|General edit route| D[Controlled action loop]
C --> C1[Use approved targets]
C1 --> C2[Generate or update files]
C2 --> C3[Read back changed files]
C3 --> C4[Finish]
D --> D1[Ask AI for next action]
D1 --> D2[Validate action]
D2 --> D3[Execute allowed action]
D3 --> D4[Return tool result to AI]
D4 --> D5{Finish / Continue / Block}
D5 -->|Continue| D1
D5 -->|Finish| D6[Finish]
D5 -->|Block| D7[Blocked]
When the target is clear, such as a create or modify task with specified files, ParrotCode handles it as a bounded route.
Examples include creating a specified file, creating multiple specified files, modifying only specified existing files, or handling a small mixed create/modify task with explicit targets.
In this case, ParrotCode fixes the target files and constraints first. It avoids unnecessarily broad exploration or long autonomous loops and prioritizes finishing in small, reviewable units.
Examples of bounded routes
- Create one specified file
- Create multiple specified files
- Modify one specified file
- Modify multiple specified files
- Create and modify multiple specified files in one bounded task
- Handle small, clearly targeted light edits without a long general loop
After changes are made, the created or modified files are read back and displayed in the timeline.
Removing content inside a file is treated as a file modification. Deleting, moving, or renaming the file itself is treated as a manual file-system operation instead of an automatic AI edit.
When the target cannot be fully fixed in advance, or when investigation is needed before editing, the AI response is handled as an action.
However, this loop is not an autonomous loop where the AI can keep moving freely.
Every action produced by the AI is validated by ParrotCode.
AI response
↓
Action parse
↓
Schema validation
↓
Mode / Level / Route validation
↓
Access confirmation
↓
Tool execution
↓
Timeline output
↓
Next AI request or finish
If the AI produces an operation that is not allowed, the operation is not executed and the block reason is displayed.
AI responses are not executed as-is.
ParrotCode interprets an AI response as an action and checks it before execution.
Path check
Whether it is trying to touch something outside the selected project
Mode check
Whether the operation is allowed in the current mode
Level check
Whether it exceeds the selected level
Route check
Whether it deviates from the task route decided in advance
Read-back check
Whether the required read-back confirmation after editing was done
Access check
Whether confirmation is required in Confirm mode
Because of these checks, if the AI tries to edit during Plan mode, modify a file outside the specified scope, or finish without the required confirmation, the run is stopped.
In ParrotCode, the user's execution settings take priority over the AI output.
In ParrotCode, AI responses, tool execution results, changed files, and hook results remain in the timeline.
User prompt
AI response
Tool result
Changed files
Hook result
Run metrics
Manual file operation handoff results
This makes it possible to review what the AI did later.
Rather than letting the AI run for a long time and only checking the final result, ParrotCode emphasizes seeing what operations were performed, where the run stopped, and what was changed.
For this reason, ParrotCode treats not only the final result, but also the process flow, as an important output.
ParrotCode also tracks approximate AI context usage for each thread. When a thread becomes long, ParrotCode can keep a compact thread summary so that older context can be represented without sending the entire history every time.
Command Hooks are not tools that the AI freely chooses and executes.
They are user-defined local commands that run before sending a prompt to AI or after receiving an AI response.
Before send
Runs before sending to AI
After response
Runs after the AI response
Hooks run based on user settings, not AI judgment.
For example, after an AI response, you can create a Git commit or save a snapshot with restic / Kopia.
git add .
git commit -m "{{result.summary}}"
restic backup .
kopia snapshot create .
Command Hooks are not a feature for allowing AI to run arbitrary commands. They are a feature for inserting user-defined local processes before and after AI work.
ParrotCode has an internal execution loop.
However, that loop is not for letting AI freely decide goals, freely run commands, or freely keep making fixes.
The ParrotCode loop exists to check the AI-proposed actions one by one within the conditions decided by the user, and to execute only the allowed operations.
flowchart LR
subgraph Autonomous Agent
A1[AI decides next goal] --> A2[AI runs tools]
A2 --> A3[AI evaluates result]
A3 --> A1
end
subgraph ParrotCode
P1[User defines task / mode / level / access] --> P2[AI proposes action]
P2 --> P3[ParrotCode validates action]
P3 --> P4[Allowed tool runs]
P4 --> P5[Timeline and user review]
end
The closer a tool gets to full autonomy, the more it depends on strong models, fast inference, stable long-term planning, and recovery from failures.
ParrotCode does not assume that. Especially with local AI, it is often easier to handle tasks by splitting them into small units that can be checked along the way, instead of running long autonomous loops.
ParrotCode is not an environment for handing everything over to AI.
It is an AI coding environment for moving through AI-assisted code edits in small, reviewable, human-controlled steps.
The binary preview can be downloaded from GitHub Releases.
https://github.com/SecondAcNo/parrotcode-experiments/releases/tag/binary-preview
Usage is simple.
- Download the zip from the binary preview release
- Extract the zip
- Run
ParrotCode.exe
ParrotCode is currently available as a binary preview only.
To use ParrotCode, you need:
- Windows 10 / 11
- An AI API endpoint
- A local AI server
- An OpenAI-compatible API endpoint
- An AI model that can follow structured code editing instructions
ParrotCode uses OpenAI-compatible chat completion endpoints. Streaming responses are supported when the endpoint supports streaming.
If you use external tools with Command Hooks, prepare the tools you need, such as:
- Git
- restic
- Kopia
These tools are not required to use ParrotCode.
They are only needed when you want to run commits, snapshot saves, local backups, or similar operations from Command Hooks.
ParrotCode is designed to make local AI easier to handle, but model capability still matters.
Small local models can be useful when the target and requirements are clear.
On the other hand, for changes with a wide scope or higher risk, use a stronger model and review the results carefully.
| Level | Recommended model guideline | Main use |
|---|---|---|
| Lv1 | Small to medium local models | DTOs, Enums, constants, simple file creation |
| Lv2 | Medium or larger local models | Validators, mappers, formatters, calculations, decisions |
| Lv3 | Stronger local models recommended | File I/O, config loading, repositories, API clients |
| Lv4 | Stronger local models or cloud AI recommended | Services, policies, managers, coordinators |
| Lv5 | Strong models recommended | Permissions, safety controls, async processing, dangerous operations, large refactoring |
As a rough guide:
Lv1 to Lv2
If the target and requirements are clear, these are areas where smaller local models can be easier to use.
Lv3
External I/O and side effects are involved, so it is better to use a stronger model and specify the target files clearly.
Lv4 to Lv5
The impact scope can become large, so it is better to use a strong model and split the task into smaller pieces.
ParrotCode is not a tool that magically makes weak models highly capable.
Its purpose is to make local AI easier to handle by keeping tasks small, bounded, and reviewable.
ParrotCode is an experimental AI coding environment.
It is not intended for long-running, fully autonomous development. Split large refactorings and high-risk changes into smaller tasks.
Local AI may become slow or unstable depending on the model size, hardware, and prompt complexity. Result quality depends heavily on the model you use and how clearly the prompt is written. Especially with smaller models, it is important to keep the target clear, the scope small, and the result easy to review.
ParrotCode is not designed to complete review, undo, rollback, or backup workflows entirely inside the app.
Restoring changes and managing history are expected to be handled together with external tools such as Git, backups, restic, or Kopia.
Deleting a thread or removing a project removes ParrotCode's saved app history. It does not delete the actual project files.
With current small to medium local AI models, it is better to assume that vague instructions asking the model to build an MVP all at once will be very difficult. For that kind of use case, it is more realistic to use paid products such as Claude Code, Codex, Cursor, or a powerful cloud AI API, rather than trying to force it through local AI or OSS agent orchestration apps. When working with local AI, the practical approach is to keep the overall picture in your own head and use AI as something closer to autocomplete. If the human side does not understand the design or architecture needed for the desired result, it becomes difficult to control the change scope and responsibility boundaries, and the result is more likely to become inconsistent.
Depending on the model's strength, local AI is also not very suitable for handing over an entire frontend screen or design decision. LLMs do not directly judge how people react to a UI or whether something visually feels off, so design work requires concrete instructions and human review. On the other hand, local AI is easier to handle when the task is split into small backend pieces, clear logic, and limited change scopes.