https://github.com/formulahendry/agent-skill-code-runner
An Agent Skill that enables AI agents to run code snippets in multiple programming languages. Works with GitHub Copilot, Claude Code, and other skills-compatible agents.
https://github.com/formulahendry/agent-skill-code-runner
agent-skills code-runner
Last synced: 15 days ago
JSON representation
An Agent Skill that enables AI agents to run code snippets in multiple programming languages. Works with GitHub Copilot, Claude Code, and other skills-compatible agents.
- Host: GitHub
- URL: https://github.com/formulahendry/agent-skill-code-runner
- Owner: formulahendry
- License: mit
- Created: 2025-12-20T08:06:01.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2025-12-21T10:50:21.000Z (about 2 months ago)
- Last Synced: 2025-12-22T14:59:31.141Z (about 2 months ago)
- Topics: agent-skills, code-runner
- Homepage:
- Size: 22.5 KB
- Stars: 8
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Code Runner Agent Skill
[](https://agentskills.io/)
[](LICENSE)
An [Agent Skill](https://agentskills.io/) that enables AI agents to run code snippets in **35+ programming languages**. Works with GitHub Copilot, Claude Code, and other skills-compatible agents.
## Features
- 🚀 **35+ Languages**: JavaScript, Python, TypeScript, Java, C/C++, Go, Rust, Ruby, PHP, and many more
- ⚡ **Interpreted & Compiled**: Supports both interpreted languages and compiled languages (C, C++, Java, Rust)
- ⏱️ **Timeout Handling**: Configurable timeout to prevent infinite loops (default: 30 seconds)
- 🔧 **Cross-Platform**: Works on Windows, macOS, and Linux
- 📦 **Zero Dependencies**: Pure Node.js implementation, no npm install required
## Supported Languages
| Category | Languages |
|----------|-----------|
| **Web/Scripting** | JavaScript, TypeScript, PHP, CoffeeScript |
| **General Purpose** | Python, Ruby, Perl, Lua, Julia |
| **Systems** | C, C++, Go, Rust, Nim, Crystal |
| **JVM** | Java, Kotlin, Scala, Groovy, Clojure |
| **Functional** | Haskell, F#, OCaml, Elixir, Racket, Scheme, Lisp |
| **Shell** | Bash, PowerShell, Batch/CMD |
| **.NET** | C# Script, F# Script, VBScript |
| **Other** | R, Swift, Dart, AppleScript, AutoHotkey |
## Installation
### Option 1: Copy to Your Project
Copy the `.github/skills/code-runner` directory to your project:
```
your-project/
└── .github/
└── skills/
└── code-runner/
├── SKILL.md
├── scripts/
│ └── run-code.cjs
└── references/
└── LANGUAGES.md
```
### Option 2: Clone This Repository
```bash
git clone https://github.com/user/agent-skill-code-runner.git
cd agent-skill-code-runner
```
## Usage
### With AI Agents (GitHub Copilot, Claude, etc.)
Once installed, the skill is automatically discovered by compatible AI agents. Simply ask:
- *"Run this Python code: print('Hello, World!')"*
- *"Execute the JavaScript: console.log(5 + 3)"*
- *"Test this Go function..."*
The agent will use the skill's instructions and runner script to execute the code.
### Direct Script Usage
You can also run the script directly:
**Recommended (stdin - avoids escaping issues):**
```bash
echo "" | node .github/skills/code-runner/scripts/run-code.cjs
```
**Alternative (CLI argument - for simple code only):**
```bash
node .github/skills/code-runner/scripts/run-code.cjs ""
```
**Examples:**
```bash
# JavaScript (stdin)
echo "console.log('Hello, World!')" | node scripts/run-code.cjs javascript
# Python (stdin)
echo "print('Hello, World!')" | node scripts/run-code.cjs python
# Go (stdin - handles quotes perfectly)
echo 'package main; import "fmt"; func main() { fmt.Println("Hello!") }' | node scripts/run-code.cjs go
# Multi-line Java (PowerShell inline here-string)
@"
public class Test {
public static void main(String[] args) {
System.out.println("Hello from Java!");
}
}
"@ | node scripts/run-code.cjs java
# Simple code via CLI argument
node scripts/run-code.cjs javascript "console.log(5 + 3)"
# With custom timeout (in milliseconds)
echo "import time; time.sleep(5); print('Done')" | node scripts/run-code.cjs python --timeout 10000
```
## Prerequisites
The script requires the appropriate interpreter or compiler for each language to be installed and available in your `PATH`:
| Language | Required |
|----------|----------|
| JavaScript | [Node.js](https://nodejs.org/) |
| TypeScript | [ts-node](https://typestrong.org/ts-node/) (`npm i -g ts-node typescript`) |
| Python | [Python](https://python.org/) |
| Java | [JDK](https://adoptium.net/) |
| C/C++ | GCC/G++ or Clang |
| Go | [Go](https://go.dev/) |
| Rust | [Rust](https://rustup.rs/) |
| Ruby | [Ruby](https://ruby-lang.org/) |
See [references/LANGUAGES.md](.github/skills/code-runner/references/LANGUAGES.md) for the complete list.
## How It Works
1. **Skill Discovery**: AI agents read the `SKILL.md` file to understand what the skill does
2. **Activation**: When a user asks to run code, the agent activates the skill
3. **Execution**: The agent uses `scripts/run-code.cjs` to:
- Create a temporary file with the code
- Execute it with the appropriate interpreter/compiler
- Return stdout/stderr to the user
4. **Cleanup**: Temporary files are automatically deleted
## Security Considerations
⚠️ **Warning**: Running arbitrary code can be dangerous. The skill includes guidance for agents to:
- Review code before execution
- Be cautious with file system access, network requests, and system commands
- Confirm execution with users when appropriate
For untrusted code, consider running in a sandboxed environment (Docker, VM, etc.).
## Troubleshooting
### Escaping Issues (Java, quotes, special characters)
**Problem**: Code with quotes or special characters fails with "illegal escape character" or similar errors.
**Solution**: Use stdin instead of CLI arguments:
```bash
# ✓ Good (stdin)
echo "System.out.println(\"Hello\");" | node run-code.cjs java
# ✗ Bad (CLI argument - escaping nightmare)
node run-code.cjs java "System.out.println(\"Hello\");"
```
**For AI Agents**: Always use stdin when calling the script to avoid shell escaping issues across different platforms.
### Language Not Found
**Problem**: `Command not found` error
**Solution**: Install the required interpreter/compiler and ensure it's in your PATH:
```bash
# Check if installed
python --version
java -version
node --version
```
## Project Structure
```
.github/skills/code-runner/
├── SKILL.md # Skill definition and instructions
├── scripts/
│ └── run-code.cjs # Code execution script (CommonJS)
└── references/
└── LANGUAGES.md # Detailed language reference
```
## Agent Skills Specification
This skill follows the [Agent Skills](https://agentskills.io/) open standard:
- **name**: `code-runner`
- **description**: Run code snippets in 30+ programming languages
- **location**: `.github/skills/code-runner/`
Compatible with:
- [GitHub Copilot](https://github.com/features/copilot) (VS Code, CLI, Coding Agent)
- [Claude Code](https://claude.ai/code)
- [Cursor](https://cursor.com/)
- Other skills-compatible agents
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
### Adding a New Language
1. Add the language config to `languageConfig` in `scripts/run-code.cjs`
2. Update the language table in `SKILL.md`
3. Add detailed info in `references/LANGUAGES.md`
## License
MIT License - see [LICENSE](LICENSE) for details.
## Related Projects
- [vscode-code-runner](https://github.com/formulahendry/vscode-code-runner) - VS Code extension for running code
- [mcp-server-code-runner](https://github.com/formulahendry/mcp-server-code-runner) - MCP Server for code execution
- [Agent Skills](https://agentskills.io/) - Open standard for AI agent capabilities