coconut
CLAUDE.md4.4k starsChanged 11 months agoApache-2.0View on GitHub
Tests can take a long time, especially when recompiling everything, so make sure to run them with a long timeout. coconut/root.py - Python 2/3 compatibility layer. Every module imports from coconut.root import *. Defines version constants and base header. coconut/constants.py - Global configuration: version info, platform detection flags (PY26...PY314, WINDOWS, PYPY, CPYTHON), dependencies, magic numbers, environment variables. coconut/compiler/: - compiler.py - Compiler class inheriting from Grammar. Main compilation logic. - grammar.py - Grammar class with PyParsing rules and basic handlers.…
Trending
Quiet since June.about the whole repository
Who's talking about evhub/coconut
- ipython/ipython“Coconut kernels not working”GitHub · Sep 2, 2020 · 4 reactions
- A Hacker News story“Coconut: Simple, elegant, Pythonic functional programming”Hacker News · Nov 27, 2023 · 3 points
- A Hacker News story“Coconut: Simple, elegant, Pythonic functional programming”Hacker News · Sep 25, 2022 · 2 points
- pure-py/pure-py-spec“Related work”GitHub · Jun 24, 2026 · 1 reactions
- NixOS/nixpkgs“python312Packages.coconut: 3.1.1 -> 3.1.2”GitHub · Sep 1, 2024
The biggest 5 of 16 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 16
Talked about on GitHub and Hacker News (16 times).
On GitHub · 14
- Sep 2, 2020Coconut kernels not working — ipython/ipython4 reactions · 2 comments
- Jun 24, 2026Related work — pure-py/pure-py-spec1 reaction · 1 comment
- Sep 1, 2024python312Packages.coconut: 3.1.1 -> 3.1.2 — NixOS/nixpkgs0 reactions · 1 comment
- Jun 22, 2024Coconut — github-linguist/linguist0 reactions
- Jun 30, 2023build(deps-dev): update coconut requirement from <2.3.0,>=1.4.3 to >=1.4.3,<3.1.0 — executablebooks/MyST-NB0 reactions · 1 comment
9 more on GitHub
- Jun 20, 2023Building PyPy doesn't work — MatteoH2O1999/setup-python0 reactions · 2 comments
- May 4, 2023Update coconut requirement from <2.3.0,>=1.4.3 to >=1.4.3,<3.1.0 — executablebooks/MyST-NB0 reactions · 1 comment
- Apr 21, 2023Update coconut requirement from ~=1.4.3 to >=1.4.3,<2.3.0 — executablebooks/MyST-NB0 reactions · 1 comment
- Oct 27, 2022coconut: 1.6.0 → 2.1.0 — NixOS/nixpkgs0 reactions · 2 comments
- Nov 3, 2020coconut: init at 1.4.3 — NixOS/nixpkgs0 reactions · 7 comments
- Jul 8, 2020coconut 1.4.3 (new formula) — Homebrew/homebrew-core0 reactions · 2 comments
- Mar 8, 2018Extend syntax highlighting to Coconut-specific keywords — cs121-team-panda/coconut-interpreter-react0 reactions · 2 comments
- Aug 15, 2017Add Coconut recipe — conda-forge/staged-recipes0 reactions · 1 comment
- May 1, 2017Conda skeleton does not support environment markers — conda/conda-build0 reactions · 2 comments
On Hacker News · 2
- Nov 27, 2023Coconut: Simple, elegant, Pythonic functional programming3 points
- Sep 25, 2022Coconut: Simple, elegant, Pythonic functional programming2 points
The file
We split this CLAUDE.md into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 70
Module imports: Always include from coconut.root import * at the top for version compatibility
- Very specific: line 71
Logging: Use logger from coconut.terminal for console output
- Distinctive: line 73
Author attribution: Add yourself to "Authors:" in module docstrings when modifying files
- Distinctive: line 83
When investigating a failed GitHub Actions job, use the GitHub API directly:
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Project Overview
Coconut is a functional programming language that compiles to Python. It adds features like pattern matching, algebraic data types, partial application, pipeline operators, and lazy evaluation on top of Python syntax. The compiler performs one-pass compilation using PyParsing. If you are ever uncertain about what the intended behavior should be, refer to the documentation in DOCS.md.
Common Commands
Development Setup
make dev # Install development environment with all dependencies and pre-commit hooksTesting
Tests can take a long time, especially when recompiling everything, so make sure to run them with a long timeout.
make test # Recompile all test files and run them (should be used whenever testing any changes to the compiler itself)
make test-tests # Just recompile changed test files and run them (much faster, but should only be used when the change being tested is just a change to the tests themselves)Running Coconut Code Directly
python -m coconut -c "your code here" # Compile and execute Coconut code passed as a stringArchitecture
Compilation Pipeline
- Pre-processing: String replacement markers handle special cases (
coconut/compiler/compiler.py) - One-pass compilation: PyParsing grammar with attached handlers transform Coconut to Python (
coconut/compiler/grammar.py) - Post-processing: Generated header prepended to output (
coconut/compiler/header.py)
Core Modules
coconut/root.py - Python 2/3 compatibility layer. Every module imports from coconut.root import *. Defines version constants and base header.
coconut/constants.py - Global configuration: version info, platform detection flags (PY26...PY314, WINDOWS, PYPY, CPYTHON), dependencies, magic numbers, environment variables.
coconut/compiler/:
compiler.py-Compilerclass inheriting fromGrammar. Main compilation logic.grammar.py-Grammarclass with PyParsing rules and basic handlers.matching.py-Matcherclass for pattern matching compilation (match statements, destructuring, pattern-matching functions).header.py- Generates runtime header fromtemplates/header.py_template.
coconut/command/:
command.py-Commandclass; CLI entry point viastartmethod.cli.py-ArgumentParserfor command-line arguments.util.py-Prompt(syntax-highlighted input),Runner(executes compiled Python).
coconut/icoconut/ - Jupyter kernel implementation (subclasses IPython kernel).
Key Entry Points
coconut/main.py- Entry points forcoconutandcoconut-runCLI commandscoconut/api.py- External API for programmatic usagecoconut/convenience.py- High-level functions:cmd(),version(),parse(),setup()
Testing
Tests are written in Coconut (.coco files), not Python. Located in coconut/tests/src/:
cocotest/agnostic/- Version-agnostic tests (main.coco, suite.coco, util.coco)cocotest/target_*/- Version-specific tests
To add tests: write Coconut code with assert statements in the appropriate .coco test file.
Code Conventions
- Module imports: Always include
from coconut.root import *at the top for version compatibility - Logging: Use
loggerfromcoconut.terminalfor console output - Exceptions: Custom hierarchy in
coconut/exceptions.py - Author attribution: Add yourself to "Authors:" in module docstrings when modifying files
Branches
master- Stable releasesdevelop- Active development (default branch for contributions)
Debugging GitHub Actions
Viewing Logs for a Specific Job
When investigating a failed GitHub Actions job, use the GitHub API directly:
gh api repos/evhub/coconut/actions/jobs/{job_id}/logsReplace {job_id} with the job ID from the URL (e.g., for .../job/59132870840, use 59132870840).
Note: The more common gh run view {run_id} --log-failed command doesn't work if the overall run is still in progress, even if the specific job you want has already completed. Using the API directly bypasses this limitation.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

